API requests and environments

Shared API library

Open Settings → OpenAPI, or API → API Library, to see all imported OpenAPI/Swagger documents—even those not linked to a project. Import from a file or URL, reload from source, and link or unlink a specification through its actions menu.

Importing into the shared library does not automatically assign it to a project. One spec can be linked to several projects; each has independent environments and credentials. Reloading the document updates all linked projects. Unlinking closes that project’s request tabs but retains environments and saved requests for relinking.

Remove an API from the library only after unlinking it everywhere. Removal requires confirmation and removes stored spec revisions, not source files or historical recordings.

Contract checks and comparison

Captured traffic is matched against the originating project’s linked APIs and environment URLs, not whichever project is currently open. In Network, Contract shows the matched operation and request/response issues; Open in API navigates to the endpoint.

Turn automatic checks on or off in Settings → OpenAPI → Automatically check network requests and responses. An unmatched, truncated, unsupported, or incompletely captured request is not proof of a valid contract.

Health shows observed coverage and violations for the selected device. Compare compares imported specifications, not captured requests. Choose an older spec, review the endpoint counts, then press Start Compare. Selecting the tab or candidate does not start work automatically. Nested schema counts are not known until comparison runs; results are a static check, not a complete compatibility guarantee.

Build & Send tabs

Select an endpoint and click Build & Send, or choose it from the endpoint’s right-click menu. The request opens in a closeable tab alongside the fixed Endpoints, Health, and Compare controls.

Edit parameters, headers, and body, choose an environment, then send. The lower pane shows response data. Requests run from the Mac, not from the selected device, and can change the target server’s data. Review the destination and payload first.

Tabs retain drafts across inspector/project switches. Right-click to duplicate; an orange dot marks unsaved edits. Closing cancels an active send, discards the draft, and asks for confirmation for edited/duplicated tabs. Unsaved drafts and responses do not survive app restarts. Limits are 12 tabs per API and 32 overall.

Inactive completed responses can move to an encrypted temporary cache after 60 seconds. Returning restores them without resending; this cache is not persistent request history.

Environments and shared authentication

Open Spec Actions → Environments, or Build & Send → Manage Environments…. Environments are named, individually editable entries—not a textarea of URLs.

1. Add an environment such as Development or Staging and enter its base URL, including any required base path.
2. Enable bearer authentication and paste the token alone, without the Bearer prefix.
3. Add API keys, choosing Header or Query and the exact parameter name. Bearer and API keys can be used together.
4. Add shared headers such as X-Tenant-ID or Accept-Language.
5. Save and select that environment in the builder. Its defaults apply across endpoints for this project/API, and the selection is remembered.

Imported security schemes can suggest API-key names and locations; reload older imports to pick up those suggestions. For a scheme named apiKey with in: query, choose Query and enter apiKey as the parameter name. Authentication is static bearer/API-key configuration, not an OAuth sign-in or automatic token-refresh flow.

Inheritance rules

• Blank endpoint headers inherit environment defaults; nonempty endpoint headers override them case-insensitively.
• Enabled environment authentication takes precedence over endpoint fields with the same name. Disable that authentication entry for a request-specific override.
• Inherited headers/API keys can satisfy required Swagger parameters.
• Manual URL sends no inherited environment settings. Edit an environment’s URL in Manage Environments.
• Environment URLs also inform contract matching; changing credentials does not revalidate captured traffic.

These settings affect manual Build & Send requests only. They do not inject credentials into connected-device requests or proxy traffic.

Credential storage and sending safeguards

Names, base URLs, and selections are project preferences. Tokens, API keys, and all shared-header values use a local, non-synchronizing Keychain item per project/API. Keychain access happens when needed by the editor/builder, not at startup. Access failures block saving or sending with that environment.

Authenticated environments require HTTPS except for localhost development addresses. TLS verification stays enabled, and manual requests do not follow redirects. Query API keys can still be logged by the receiving server. Copy URL redacts configured query API-key values, but other URL values remain; responses can echo secrets too.

Deleting an environment requires confirmation and takes effect on Save. Unlinking a spec retains its environments; deleting the project removes its credentials.

Saved requests, history, and preview

Use Spec Actions → Saved Requests & History, or Request → Saved Requests in the builder, to save named drafts and optional folders. Saved request values use local Keychain storage per project/API; environment credentials are referenced rather than copied. Deleting a saved request requires confirmation.

History keeps the latest 100 completed/failed sends for the current app session. It records endpoint, time, and outcome—not request values or response bodies. Opening a history item starts a fresh draft.

Request → Masked Preview resolves and validates a request without sending it, hiding header/query/body values and substituted path values. Review this before sharing configuration. It is distinct from Copy URL.