API

The Sazabi public API is a REST API. Every endpoint page in this section is generated from the committed public OpenAPI contract, so the reference always matches the deployed API.

Base URL

All requests go to the versioned production base URL:

https://api.sazabi.com/v1

The path prefix /v1 is the API version. Prepend the base URL to every endpoint path shown in this reference.

Authentication

Authenticate with a secret key. Create one in the dashboard under Settings > Secret keys. Secret keys are organization-scoped and grant read/write access to the API, so keep them server-side only.

Send the key as a bearer token:

curl https://api.sazabi.com/v1/me \
  -H "Authorization: Bearer $SAZABI_SECRET_KEY"

Public keys are for log ingestion, not the API — see Keys for the distinction. A missing or invalid credential returns 401.

Errors

Errors return a non-2xx HTTP status and a JSON body with the error fields at the top level. The code field carries a stable machine-readable code, and operationId names the endpoint that failed:

{
  "code": "NOT_FOUND",
  "message": "Automation not found",
  "operationId": "automations.get",
  "missingContext": []
}

Some responses also include reason (a machine-readable sub-code) and, on 429, retryAfterSeconds. missingContext lists any required context that was absent from the request.

Branch on the top-level code field rather than parsing message; messages are for humans and can change.

Rate limits

The API enforces per-organization and per-key request rate limits. When you exceed one, the API returns 429 with code TOO_MANY_REQUESTS. Back off and retry. For the shape of these limits, see Limits.

Pagination

The API uses two pagination strategies. Check each endpoint's generated schema to see which one it uses.

Cursor-based (most list endpoints). The response carries a nextCursor; pass it back as the cursor query parameter to fetch the next page. A null nextCursor means there are no more results.

curl "https://api.sazabi.com/v1/threads?cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SAZABI_SECRET_KEY"

Page-based. /v1/search/threads, /v1/search/messages, and /v1/billing/transactions take a one-based page query parameter and return a pagination object with page, limit, totalPages, and a total count (totalResults for search, total for billing transactions). Increment page until you reach totalPages.

curl "https://api.sazabi.com/v1/search/threads?page=2" \
  -H "Authorization: Bearer $SAZABI_SECRET_KEY"

Streaming

Agent runs and threads stream events over Server-Sent Events. See Streaming.

In this section

Browse every operation by resource in the sidebar, or start from a resource group below: