---
title: "API conventions"
sidebarTitle: "Conventions"
description: "Idempotency, errors, pagination and versioning for Trillet OEM."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

<Note>
  **Early access.** Trillet OEM is built and in testing with design partners. Contact your account manager to have it enabled for your account. Details may still change.
</Note>

- **Base URL:** `https://api.trillet.ai/partner/v1`
- **Format:** JSON request and response bodies, UTF-8. Timestamps are ISO 8601 UTC, except `created` on events, which is Unix seconds.
- **IDs:** Tenant, number, call flow, endpoint and key IDs are 24-character hexadecimal strings. Event IDs start with `evt_`. Store all IDs as strings.
- **Objects:** Every response object has an `object` field, for example `tenant`, `phone_number`, `call_flow_settings`, `event` or `list`.

## Idempotency

Networks fail. Endpoints that create something billable or hard to undo require an `Idempotency-Key` header, so a retry never creates it twice. On the call flow settings endpoint the header is optional. Other `/partner/v1` endpoints ignore it.

| Endpoint | `Idempotency-Key` |
|---|---|
| `POST /partner/v1/tenants` | Required |
| `POST /partner/v1/tenants/{tenantId}/numbers` | Required |
| `POST /partner/v1/tenants/{tenantId}/numbers/external` | Required |
| `PATCH /partner/v1/tenants/{tenantId}/call-flows/{callFlowId}/settings` | Optional |

```bash
curl -X POST https://api.trillet.ai/partner/v1/tenants \
  -H "Authorization: Bearer tpk_live_..." \
  -H "Idempotency-Key: create-tenant-cust_8842" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "cust_8842", "name": "Harbour Dental" }'
```

| Situation | Result |
|---|---|
| First request with a key | Runs normally. The response is stored for 24 hours. |
| Retry with the same key and the same request | The stored response is returned with the header `Idempotent-Replayed: true`. Nothing runs twice. |
| Same key, different request | `422` `idempotency_key_reused` |
| Same key while the first request is still running | `409` `idempotency_key_in_use`. Retry after `Retry-After`. |
| No key on an endpoint that requires one | `400` `idempotency_key_required` |
| The first request failed with a `5xx`, `401`, `403`, `409` or `429` | Not stored. A retry runs again. |
| The first request failed with any other `4xx`, for example `402` `insufficient_funds`, `400` `number_purchase_failed` or `404` | Stored and replayed for 24 hours like a success. After you fix the cause (add funds, add the regulatory bundle, correct the field), retry with a **new** key. A body that fails the endpoint's schema is refused before the key is checked, so that `400` is not stored. |

- Keys are 1 to 255 printable ASCII characters, with no spaces, and are scoped to your partner account. A UUID, or your own operation ID, works well. A key that does not fit returns `400` `idempotency_key_invalid`.
- "The same request" means the same method, path, query string and JSON body. Key order in the body does not matter.
- If a request is interrupted before it finishes, the key is locked for up to 2 minutes, after which a retry can run.

Idempotency errors have `type: "idempotency_error"` and no `requestId`.

## Errors

Every other error has the same shape:

```json
{
  "error": {
    "type": "conflict_error",
    "code": "tenant_deleted_restorable",
    "message": "A deleted tenant d9d9d9d9d9d9d9d9d9d9d9d9 has this externalId. Restore it, or use a different externalId.",
    "requestId": "req-1a2b"
  }
}
```

`param` is included when the error is about one request field, for example a body field that failed validation. Handle errors by `code`, not by `message`. Include `requestId` when you contact support.

| Status | `type` | Meaning |
|---|---|---|
| `400` | `invalid_request_error` | The request is malformed or a field is invalid (`invalid_request`, or a specific code such as `invalid_external_id`) |
| `401` | `authentication_error` | Authentication failed. See [Authentication](https://trillet-ai.jamdesk.app/voice-engine/authentication#authentication-errors). |
| `402` | `invalid_request_error` | `insufficient_funds`: your account cannot pay for a number purchase |
| `403` | `permission_error` | The key is not allowed to do this |
| `404` | `invalid_request_error` | Not found, or not yours |
| `409` | `conflict_error` | Conflict, for example a duplicate `externalId` or a tenant limit |
| `410` | `invalid_request_error` | `restore_window_expired`: a tenant deleted more than 30 days ago |
| `429` | `rate_limit_error` | Rate limited |
| `500` | `api_error` | A problem on our side. Safe to retry with the same `Idempotency-Key`. |

Each page lists the codes its endpoints return.

## Pagination

List endpoints return a page, newest first:

```json
{
  "object": "list",
  "data": [ { "object": "tenant", "id": "d9d9d9d9d9d9d9d9d9d9d9d9" } ],
  "hasMore": true
}
```

To get the next page, pass the `id` of the last item as `starting_after`, with an optional `limit`:

```bash
curl "https://api.trillet.ai/partner/v1/tenants?limit=50&starting_after=d9d9d9d9d9d9d9d9d9d9d9d9" \
  -H "Authorization: Bearer tpk_live_..."
```

| List | `limit` |
|---|---|
| `GET /tenants` | 1 to 100, default 20 |
| `GET /events` | 1 to 100, default 20 |
| `GET /usage/calls` | 1 to 200, default 50 |

`GET /tenants/{tenantId}/numbers` and `GET /webhook-endpoints` return every item in one page.

## Versioning

The major version is in the path (`/partner/v1`). Within a version we only add things: new endpoints, new optional fields, new event types. Your code should ignore fields and event types it does not recognise.

Every response carries a `Trillet-Version` header with the date of the API release that served it, for example `Trillet-Version: 2026-10-28`. It is informational: requests cannot pin a version yet. Version pinning by request header is planned.

## Rate limits

During early access there is no published per-key request limit. Repeated invalid keys from one IP address (20 in a minute) are refused with `429` `rate_limited` for the rest of that minute. Tell your account manager about expected volumes before large provisioning runs.
