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

# API reference

> How the Tirdad REST API is organised, and where each part of the reference lives

The REST API is the source of truth for everything in Tirdad. The [API Reference tab](https://docs.tirdad.ai/api-reference/introduction.md) is generated from the same OpenAPI document that produces the SDKs and the MCP server, so an endpoint documented there behaves identically in every client.

## API conventions at a glance

| Topic | Summary | Full page |
| - | - | - |
| Base URLs | `https://api.tirdad.ai/v1`. | [Introduction](https://docs.tirdad.ai/api-reference/introduction.md) |
| Authentication | Send your key in the `x-api-key` header on every request. A key is bound to one environment, so there is no environment parameter. | [Manage API keys](https://docs.tirdad.ai/docs/rbac/manage-api.md) |
| Request format | JSON bodies with `snake_case` fields. List endpoints are `POST /<resource>/search` with a filter body. | [Introduction](https://docs.tirdad.ai/api-reference/introduction.md) |
| Pagination | Offset based. Send `limit` and `offset`, read `pagination.offset` back for the next page, up to 1000 items per page. | [Pagination](https://docs.tirdad.ai/api-reference/pagination.md) |
| Errors | `{"success": false, "error": { "message": "..." }}` with a standard HTTP status. `409` is safe to retry. | [Error responses](https://docs.tirdad.ai/api-reference/error-responses.md) |
| Idempotency | Events dedupe on `event_id` and `timestamp` together. Invoices, credit notes, wallet top-ups, and portal payments accept an `idempotency_key` field. | [Idempotency and deduplication](https://docs.tirdad.ai/docs/core-concepts/usage-events/idempotency.md) |
| Async ingestion | `POST /events` and `POST /events/bulk` return `202 Accepted`. Bulk accepts up to 1000 events per call. | [Send Usage Events](https://docs.tirdad.ai/docs/core-concepts/usage-events/sending-events.md) |
| Rate limits | `429 Too Many Requests` when you exceed the limit. Back off and retry. | [Error responses](https://docs.tirdad.ai/api-reference/error-responses.md) |

## API endpoints by billing lifecycle

The reference groups endpoints by resource. Read them in the order a billing lifecycle runs:

**1. Catalog**

[Features](https://docs.tirdad.ai/api-reference/features/create-feature.md), [Plans](https://docs.tirdad.ai/api-reference/plans/create-plan.md), [Prices](https://docs.tirdad.ai/api-reference/prices/create-price.md), [Entitlements](https://docs.tirdad.ai/api-reference/entitlements/create-entitlement.md), [Addons](https://docs.tirdad.ai/api-reference/addons/create-addon.md), [Coupons](https://docs.tirdad.ai/api-reference/coupons/create-coupon.md), [Credit Grants](https://docs.tirdad.ai/api-reference/credit-grants/create-credit-grant.md)

**2. Customers and subscriptions**

[Customers](https://docs.tirdad.ai/api-reference/customers/create-customer.md), [Subscriptions](https://docs.tirdad.ai/api-reference/subscriptions/create-subscription.md), [Wallets](https://docs.tirdad.ai/api-reference/wallets/create-a-new-wallet.md), [Checkout](https://docs.tirdad.ai/api-reference/checkout/create-checkout-session.md)

**3. Usage**

[Events](https://docs.tirdad.ai/api-reference/events/ingest-event.md), [Usage analytics](https://docs.tirdad.ai/api-reference/events/get-usage-analytics.md), [Customer entitlements](https://docs.tirdad.ai/api-reference/customers/get-customer-entitlements.md)

**4. Billing**

[Invoices](https://docs.tirdad.ai/api-reference/invoices/create-one-off-invoice.md), [Payments](https://docs.tirdad.ai/api-reference/payments/create-payment.md), [Credit Notes](https://docs.tirdad.ai/api-reference/credit-notes/create-credit-note.md), [Refunds](https://docs.tirdad.ai/api-reference/refunds/list-refunds.md)

**5. Platform**

[API keys](https://docs.tirdad.ai/api-reference/secrets/create-a-new-api-key.md), [Users](https://docs.tirdad.ai/api-reference/users/create-user-or-service-account.md), [Tenants](https://docs.tirdad.ai/api-reference/tenants/get-tenant-by-id.md), [Environments](https://docs.tirdad.ai/api-reference/environments/clone-an-environment.md), [Integrations](https://docs.tirdad.ai/api-reference/integrations/link-integration-mapping.md)

## Webhook payload reference

The reference also documents every webhook payload under **Webhook Events**. Those pages describe the JSON Tirdad sends to you, not endpoints you call. Start from the [event catalog](https://docs.tirdad.ai/developers/webhooks/event-catalog.md) to find the event you want.

## Customer portal API endpoints

Endpoints under `/v1/customer/portal` authenticate with a short-lived session token instead of an API key and are scoped to one customer. They are documented separately in the [Portal API reference](https://docs.tirdad.ai/docs/customers/customer-portal/api-reference.md).

## Trying an endpoint in the playground

Every endpoint page in the reference has a playground. Paste an API key, and send a request from the browser.

> [card] [Open the API Reference](https://docs.tirdad.ai/api-reference/introduction.md)

> [card] [Download the OpenAPI spec](https://docs.tirdad.ai/developers/api-tooling/openapi-spec.md)

> [card] [Use an SDK instead](https://docs.tirdad.ai/developers/sdks/overview)


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