API Testing: API Sources
Overview
Use this page to add and sync OpenAPI specification sources. An API source is a registered OpenAPI document, either fetched automatically from a Spec URL or uploaded manually as a file, that LoadGen tracks over time. Without a source, there is nothing for API Testing to build structured, spec-aware flows against: every endpoint and schema a flow can call originates from a version imported here.
This page sits at the start of the API Testing workflow. Before you add a source you need the OpenAPI document itself: either a reachable Spec URL, or a .json, .yaml or .yml file from the team that owns the API. Once a version is imported, it feeds API Testing: Flows, where flows are built or migrated against that version, then run through schedules and show up in run history.
On this page you register new sources, trigger or configure automatic refreshes, expand a source to review its imported versions, compare versions with the diff viewer, check spec coverage and conformance, and see which flows are impacted before you migrate or delete a source.
Key concepts
- API source - A registered OpenAPI specification, either fetched from a Spec URL or uploaded as a file, that LoadGen keeps in sync and tracks version by version. (related: API Testing: Flows)
- Spec version - A snapshot of a source's OpenAPI document captured at one point in time. A source gains a new version each time an import finds the spec has changed. (related: API Testing: Flows)
- Auto-refresh - A per-source setting that has LoadGen periodically re-fetch the Spec URL on its own, instead of you clicking Refresh Now each time.
- Manual source - A source with no Spec URL. Instead of polling an endpoint, you add new versions by uploading a spec file directly.
- Impacted flows - The API Testing flows built against a source's spec, which may need review or migration when that spec's version changes. (related: API Testing: Flows)
When to use it
- You're setting up API Testing for a new API and need to register its OpenAPI specification before building flows.
- An API you already test has changed and you want to pull in the latest spec and see what changed.
- You want to check whether a spec update breaks any existing flows before migrating them.
- You maintain a spec with no reachable URL and need to upload it as a file instead of pointing to an endpoint.
- You're reviewing which flows depend on a given source before deleting or replacing it.
Before you begin
- You have the OpenAPI specification's URL, or a .json, .yaml or .yml file of it (max 10 MB) if it has no reachable URL.
- Your account role grants permission to create, edit, refresh or delete API sources; without it, Add Source and the row actions for upload, refresh, edit and delete are disabled or replaced with a read-only view.
- If you plan to build or migrate flows once a source syncs, know which flows you intend to create or update on API Testing: Flows.
Common workflows
Add a new API source and sync its first version
Persona: API test engineer
- Click Add Source.
- Expect: The add-source dialog opens with Name, Spec URL, Description, Auto-refresh and Spec file fields.
- Enter a Name and a Spec URL (or leave the URL blank and use Spec file to upload the document instead), then save.
- Expect: A new row appears in the table showing Status Pending, 0 Versions, and Auto-Refresh matching the toggle you set.
- Click Refresh Now on the new row (or Upload spec if it has no Spec URL).
- Expect: The row updates: Status changes from Pending, Versions increases, and Latest Version and Last Refresh populate.
Verify: The new source shows a non-zero Versions count, a Latest Version value, and a Last Refresh timestamp instead of a dash.
Review a spec change and migrate an impacted flow
Persona: API test engineer
- Click the expand chevron on a source whose Status or Diff Summary indicates a new version.
- Expect: The row opens to show its version history and the flows listed under Impacted Flows.
- Click Diff on the latest version.
- Expect: The diff viewer opens, comparing the latest version against the one before it.
- Click Migrate next to an impacted flow that is affected by the change.
- Expect: The migration wizard opens for that flow.
Verify: The flow's migration wizard reflects the new spec version, and the Impacted Flows count drops once you reload the source list after migrating all affected flows.
Steps
Step 1
Open API Sources under API Testing.
Expected result: The page loads the list of configured OpenAPI sources; in this capture two sources are listed, both showing Status Pending, 0 Versions, and Auto-Refresh Off because neither has completed an initial import yet.
This is the starting point for adding, syncing or reviewing the OpenAPI specifications that API Testing flows are built from.
- Add Source opens the dialog for registering a new OpenAPI spec.
- The chevron at the start of each row expands it to show version detail.
- A Status of Pending means the source has not yet completed its first spec import.
Field reference
| Field | Purpose | Format / Validation | Required | Default |
|---|---|---|---|---|
| Name | The display name for the source you are adding or editing. | free text | Yes | - |
| Spec URL | The endpoint LoadGen polls for the OpenAPI document. Leave it blank to make this a manual source and supply the spec by file upload instead; fill it in so Refresh Now and Auto-refresh have something to fetch. | URL | No | - |
| Description | A free-text note to help identify the source's purpose; it has no effect on syncing or flows. | free text | No | - |
| Auto-refresh | Turns on periodic automatic checking of the Spec URL. Enable it to catch upstream spec changes without remembering to click Refresh Now; leave it off if you prefer to control exactly when a refresh happens, for example before a migration. | toggle | No | Off |
| Spec file (.json / .yaml / .yml, max 10 MB) | Uploads the OpenAPI document directly for a manual source, or supplies a new version when the source has no URL to refresh from. | file upload | No | - |
Column reference
| Column | What it shows | How to read it |
|---|---|---|
| Name | Identifies the source in the list and in any flow built from it. | Read it as the label you gave the source when you added it; it does not change based on sync activity. |
| Spec URL | The endpoint LoadGen fetches the OpenAPI document from when refreshing this source. | A dash here means the source is manual and has no URL to poll; refreshing it means uploading a new file instead. |
| Versions | Count of spec versions imported for this source so far. | 0 means no import has completed yet; the count increases each time a refresh or upload captures a new version. |
| Latest Version | Label of the most recently imported spec version. | A dash means no version has been imported yet; once one lands, this shows its version identifier. |
| Status | The source's current sync state. | Pending means the source was added but has not completed an initial import; Failed means the last refresh or import attempt errored, for example a manual source refreshed without a Spec URL or upload. |
| Diff Summary | Short description of what changed between the latest version and the one before it. | A dash means there is nothing to compare yet, either because only one version exists or no diff was recorded for that pair. |
| Impacted Flows | Count of API Testing flows built against this source. | This count is captured when the source list loads; a flow migrated or added after that will not be reflected until you reload the page. |
| Last Refresh | Timestamp of the most recent refresh attempt for this source. | A dash means the source has never been refreshed; once refreshed, the timestamp updates whether the attempt succeeded or failed. |
| Auto-Refresh | Whether LoadGen periodically re-fetches this source's Spec URL on its own. | Off means you must trigger refreshes manually with Refresh Now; a source with auto-refresh enabled checks the Spec URL on its own schedule without you clicking anything. |
| Actions | Row-level icons for managing this source and its versions. | Each icon opens one action (upload, refresh, edit or view, delete); icons you don't have permission to use are disabled with a tooltip explaining why. |
Controls reference
Add Source
Opens the dialog for registering a new API source, with Name, Spec URL, Description, Auto-refresh and Spec file fields.
When to use: When you need to start testing against an API that has no source registered yet.
Side effects: Mutating: saving creates a new row in the table with Status Pending and 0 Versions.
Row expand chevron
Expands the row to show that source's version history and its impacted flows.
When to use: When you want to review past versions, approve a version, or see which flows depend on this source.
Side effects: Read-only: toggles display only.
Upload spec
Opens a dialog to upload a spec file directly for this source.
When to use: For a manual source with no Spec URL, or when you want to supply a new version as a file instead of waiting on a URL fetch.
Side effects: Mutating: submitting the file adds or updates a version for that source.
Refresh Now
Re-fetches the spec from the source's Spec URL and checks for changes.
Side effects: Mutating: updates Versions, Latest Version, Status, Diff Summary and Last Refresh. Only one refresh runs at a time across sources, so this may wait while another is in progress. Not available for a manual source, which has nothing to poll.
Edit / View
Opens the source's details dialog to change Name, Spec URL, Description and Auto-refresh. Shown as View, the same dialog read-only, when your role can see these details but not change them.
When to use: When you need to correct a source's URL or name, or just want to confirm its configuration.
Side effects: Mutating when used as Edit and saved; no effect when used as View.
Delete Source
Opens a confirmation dialog, then removes the source.
When to use: When a spec is no longer needed and no flows depend on it, or you intend to replace it.
Side effects: Mutating and destructive: deletes the source. Disabled with a tooltip if your role lacks permission.
Approve
Marks a specific imported version as reviewed and approved for use.
When to use: After reviewing a newly imported version, before building or migrating flows against it.
Side effects: Mutating: updates that version's approval state.
Coverage
Opens the spec coverage and response conformance report for that version.
When to use: To check how much of the spec's endpoints are exercised and whether actual responses conform before approving or migrating.
Side effects: Read-only.
Diff
Opens the diff viewer comparing that version against the previous one.
When to use: To see exactly what changed in the spec before approving a version or migrating flows.
Side effects: Read-only. Disabled when no diff was recorded for that version pair.
Edit (impacted flow)
Opens that flow in the flow editor.
When to use: To inspect or adjust a flow that depends on this source before or after a spec change.
Side effects: Read-only navigation; it leaves this page.
Migrate (impacted flow)
Starts the migration wizard for that flow against a newer spec version.
When to use: After a spec update, for a flow listed under Impacted Flows that needs to be updated to match the new version.
Side effects: Mutating once the wizard is completed; it leaves this page.
Retry
When to use: When the page shows an error instead of the sources table.
Side effects: Read-only: reloads the list.
Verify the result
A successfully configured source shows a Name, a Spec URL (or is manual with a dash there), at least one entry under Versions, a Latest Version value, and a Status other than Pending once an import succeeds. Last Refresh shows a timestamp instead of a dash, confirming LoadGen has fetched or received the spec at least once. If Auto-Refresh is enabled, later checks happen without manual action. If Status stays Pending or turns Failed after you use Refresh Now or Upload spec, the import has not completed and no flows should be built or migrated against that source yet.
Troubleshooting
- Symptom: A new source stays at Status Pending with 0 Versions. Fix: Click Refresh Now (or Upload spec for a manual source) to trigger the first import; Auto-refresh only runs on its own schedule, so a freshly added source may not have synced yet.
- Symptom: Status shows Failed after Refresh Now. Fix: Verify the Spec URL loads directly and returns a valid OpenAPI document; for a manual source, use Upload spec instead, since there is no URL to poll.
- Symptom: Refresh Now, Upload spec, Edit or Delete Source is greyed out with a tooltip. Fix: Your role's permissions do not include write access to this source; ask an administrator to grant API source edit or delete rights.
- Symptom: The Impacted Flows count looks out of date after migrating a flow. Fix: Reload the API Sources page; the count is captured when the list loads and is not updated live.
- Symptom: The Diff button is disabled for a version. Fix: No diff was recorded for that specific version pair; check that Versions is at least 2, or compare a different adjacent pair.
- Symptom: The table shows an error instead of the source list. Fix: Click Retry; if it still fails, confirm your account has permission to view API sources.
Related articles
- Next step: API Testing: Flows - flows are built or migrated against the versions imported here
- See also: API Testing: Environments - flows built from a source run against environments configured there
- See also: API Testing: Schedules - flows depending on a source's version can be scheduled to run regularly
- See also: Operations: Permissions - role grants determine which upload, refresh, edit and delete actions are enabled here