Trillet AI logo

API conventions

Idempotency, errors, pagination and versioning for Trillet OEM.

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.

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

EndpointIdempotency-Key
POST /partner/v1/tenantsRequired
POST /partner/v1/tenants/{tenantId}/numbersRequired
POST /partner/v1/tenants/{tenantId}/numbers/externalRequired
PATCH /partner/v1/tenants/{tenantId}/call-flows/{callFlowId}/settingsOptional
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" }'
SituationResult
First request with a keyRuns normally. The response is stored for 24 hours.
Retry with the same key and the same requestThe stored response is returned with the header Idempotent-Replayed: true. Nothing runs twice.
Same key, different request422 idempotency_key_reused
Same key while the first request is still running409 idempotency_key_in_use. Retry after Retry-After.
No key on an endpoint that requires one400 idempotency_key_required
The first request failed with a 5xx, 401, 403, 409 or 429Not stored. A retry runs again.
The first request failed with any other 4xx, for example 402 insufficient_funds, 400 number_purchase_failed or 404Stored 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:

{
  "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.

StatustypeMeaning
400invalid_request_errorThe request is malformed or a field is invalid (invalid_request, or a specific code such as invalid_external_id)
401authentication_errorAuthentication failed. See Authentication.
402invalid_request_errorinsufficient_funds: your account cannot pay for a number purchase
403permission_errorThe key is not allowed to do this
404invalid_request_errorNot found, or not yours
409conflict_errorConflict, for example a duplicate externalId or a tenant limit
410invalid_request_errorrestore_window_expired: a tenant deleted more than 30 days ago
429rate_limit_errorRate limited
500api_errorA 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:

{
  "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:

curl "https://api.trillet.ai/partner/v1/tenants?limit=50&starting_after=d9d9d9d9d9d9d9d9d9d9d9d9" \
  -H "Authorization: Bearer tpk_live_..."
Listlimit
GET /tenants1 to 100, default 20
GET /events1 to 100, default 20
GET /usage/calls1 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.

Last updated on