Skip to main content

​
Import an OpenAPI spec

Import an OpenAPI 3.x or Swagger 2.0 spec when you want Qodex to start from a formal API contract. Qodex parses the spec, catalogs every endpoint, preserves schemas and auth metadata, and uses that catalog to author API scenarios.

​
Prerequisites

  • A project in Qodex.
  • An OpenAPI 3.x or Swagger 2.0 document. JSON or YAML, file or URL.
  • One environment with the base URL of the system under test.

​
1. Upload the spec

In chat, attach the .yaml, .yml, or .json file. You can also paste a public URL and Qodex will fetch and parse it. 
# Or programmatically, via the import endpoint
curl -X POST "https://agents.qodex.ai/api/p/<slug>/import/swagger" \
  -H "Authorization: Bearer $QODEX_KEY" \
  -F "file=@openapi.yaml"
Qodex validates the document and creates a collection. Every operation under paths becomes a row in the endpoint catalog with method, path, parameters, request schema, response schema, and tags preserved.

​
2. Review discovered endpoints

Open the endpoint catalog to review what was imported. Every operation appears with its method, path, summary, and tags. Filter by tag to focus on one module, such as auth, payments, or users. Filter by coverage to find endpoints with zero scenarios. The catalog row is the source of truth. Edits you make to name, headers, body, or auth persist to the same record the API Playground uses, so governance and playground do not drift.

​
3. Configure auth profiles

If your spec declares securitySchemes, Qodex preserves the structured shape on each endpoint and shows it during authoring. The agent copies it into step.auth without reinterpreting it. For runtime auth, create one auth profile per role you want to test:
  • admin for privileged operations.
  • user for regular-account access.
  • viewer for read-only checks.
Each profile carries its own credentials and login config. Scenarios run as a chosen profile at execution time, which is how IDOR, BOLA, and role-escalation tests stay clean. See Auth profiles for the full shape.

​
4. Author your first scenario from chat

In a chat, ask: 
Write a happy-path test for POST /users and a 401 test
for the same endpoint without an auth token.
The agent reads the catalog entry for POST /users, generates two scenarios, verifies them against your default staging environment, and saves both as draft. Promote them to active when you want scheduled or event-driven runs to include them.

​
Try it yourself

Endpoint catalog

Browse every endpoint Qodex has cataloged.

Scenarios

See how a generated scenario is structured.

​
Next steps

Auth profiles

Run as admin, regular user, and viewer.

API governance

See coverage across every endpoint.