# OpenAPI

> The OpenAPI 3.1 description of the TradeCatalog API, and how to use it with Postman, typed clients and API explorers.

The whole API is described in one OpenAPI 3.1 document:

```text
https://tradecatalog.app/api/v1/openapi.json
```

It’s public (no key needed) and generated from the same schemas the API uses to check requests, so it can’t drift from what the API accepts. It includes every path, parameter, request body, limit and enum value.

## Import into Postman or Insomnia

1. In Postman, choose **Import** and paste the URL above. In Insomnia, choose **Import** then **From URL**.
2. Set the collection’s auth to **Bearer Token** with your API key.

## Generate TypeScript types

[openapi-typescript](https://openapi-ts.dev) turns it into types:

```bash
npx openapi-typescript https://tradecatalog.app/api/v1/openapi.json -o tradecatalog.d.ts
```

Then use them with `openapi-fetch` for a typed client:

```js
import createClient from 'openapi-fetch'

const client = createClient({
  baseUrl: 'https://tradecatalog.app/api/v1',
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})

const { data, error } = await client.GET('/prices', {
  params: { query: { customer: 'OAK01', sku: 'HX-8510', qty: 10 } },
})
```

The document describes request parameters and bodies in full. Response bodies are described as the shared `{ data, nextOffset, currency }` envelope; the field-by-field response shapes are on each endpoint’s page in these docs.

## Other languages

Any OpenAPI generator works, for example:

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://tradecatalog.app/api/v1/openapi.json \
  -g python -o tradecatalog-client
```

## Browse it

Paste the URL into [Scalar](https://scalar.com), [Swagger Editor](https://editor.swagger.io) or any OpenAPI viewer to browse the endpoints and try requests with your key.

## For AI agents

The OpenAPI document is listed in the API catalog at `/.well-known/api-catalog`, so agents can find it on their own. See [AI and LLM resources](/docs/guides/llms).