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

# OpenAPI spec

> Where to download the Tirdad OpenAPI document and what to do with it: code generation, validation, and AI context

Tirdad publishes its API as an OpenAPI 3.0 document. The API reference, the SDKs and the MCP server are all generated from it, so the spec is the most precise description of the API that exists.

## Downloading the OpenAPI spec

| Source | URL | Notes |
| - | - | - |
| Hosted spec | `https://docs.tirdad.ai/api-reference/openapi.json` | The document behind the API Reference tab, with Go, Python, and TypeScript SDK samples on each operation (`x-codeSamples`) |

```sh theme={null}
curl -sSL https://docs.tirdad.ai/api-reference/openapi.json -o tirdad-openapi.json
```

The document declares a single server:

```json theme={null}
"servers": [
  { "url": "https://api.tirdad.ai/v1", "description": "Tirdad API" }
]
```

Authentication is a single API-key scheme, `ApiKeyAuth`, sent as the `x-api-key` header.

## What the OpenAPI spec contains

* Every endpoint, grouped by tag (Customers, Subscriptions, Events, Invoices, and so on).
* Request and response schemas, including enums such as billing periods and subscription statuses.
* A **Webhook Events** tag whose operations describe the payload Tirdad sends for each webhook event. They are documentation of what you receive, not endpoints you call. See the [event catalog](https://docs.tirdad.ai/developers/webhooks/event-catalog.md).
* Vendor extensions: `x-codeSamples` with SDK examples on each operation, and `x-codegen-request-body-name` used by generators.

## Generating a client from the spec

For a language without an official SDK, generate one:

```sh Java theme={null}
npx @openapitools/openapi-generator-cli generate \
  -i tirdad-openapi.json \
  -g java \
  -o ./tirdad-java \
  --additional-properties=library=native,useJakartaEe=true
```

```sh C# theme={null}
npx @openapitools/openapi-generator-cli generate \
  -i tirdad-openapi.json \
  -g csharp \
  -o ./tirdad-csharp
```

```sh Ruby theme={null}
npx @openapitools/openapi-generator-cli generate \
  -i tirdad-openapi.json \
  -g ruby \
  -o ./tirdad-ruby
```

Generated clients need two settings: the server URL with `/v1` and the `x-api-key` header. Both are declared in the spec, so generators expose them as configuration.

## Validating requests and mocking the API

* **Contract tests.** Load the spec into a validator such as `openapi-core` (Python) or `express-openapi-validator` (Node) to check your outgoing requests before they hit the network.
* **Mock server.** Run `npx @stoplight/prism-cli mock tirdad-openapi.json` to get a local server that answers with example responses, useful for frontend work without a sandbox key.

## Feeding the spec to an AI tool

The spec is the best single file for an agent that needs exact field names. The MCP server already loads it; for other tools, attach the JSON directly or point them at `https://docs.tirdad.ai/llms-full.txt` for the prose documentation. See [Agent Skills](https://docs.tirdad.ai/developers/ai/agent-skills.md).

## OpenAPI spec versioning

The spec has no separate version number from the API. Changes land in the [changelog](https://docs.tirdad.ai/docs/changelog.md) under **API**, and the SDKs are regenerated from the new document. Diff two downloads to see exactly what changed between releases.

> [card] [Postman collection](https://docs.tirdad.ai/developers/api-tooling/postman.md)

> [card] [Swagger UI](https://docs.tirdad.ai/developers/api-tooling/swagger-ui.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.