> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Import an OpenAPI spec

> Import an OpenAPI or Swagger spec so Qodex can catalog endpoints and create API scenarios.

# 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.

```bash theme={null}
# 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](/api-testing-auth-profiles) for the full shape.

## 4. Author your first scenario from chat

In a chat, ask:

```text theme={null}
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

<CardGroup cols={2}>
  <Card title="Endpoint catalog" icon="list" href="/api-testing-endpoint-catalog">
    Browse every endpoint Qodex has cataloged.
  </Card>

  <Card title="Scenarios" icon="list-checks" href="/api-testing-scenarios">
    See how a generated scenario is structured.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Auth profiles" icon="key" href="/api-testing-auth-profiles">
    Run as admin, regular user, and viewer.
  </Card>

  <Card title="API governance" icon="map" href="/api-testing-governance">
    See coverage across every endpoint.
  </Card>
</CardGroup>