SDKs

Both are at version 1.2.0 and are not yet published to npm or PyPI. Install from the repository:

The TypeScript client is ESM-only and needs Node.js 20 or later; it runs on your server and has no browser build. The Python client needs Python 3.10 or later and ships sync and async methods.

Request bodies are plain objects (TypeScript) or dicts (Python), exactly the JSON the endpoint takes — there are no keyword-argument wrappers. Each collection carries only the verbs the spec defines on it — list, retrieve, create, update, and del in TypeScript / delete in Python — so a method that could only answer 404 does not exist. list takes a query object, not a query string. Search, billing, analytics and request logs have their own helpers; request(method, path, body) reaches any endpoint, and autoPaging(path) / auto_paging(path) walks a cursor list.

The plumbing you would otherwise write once per project, and get subtly wrong:

• Resource helpers for every public collection, generated from the spec.
• chat.send and chat.stream, including SSE frame parsing.
• Automatic Idempotency-Key on every write, reused across retries of the same call, so a retry cannot double-write.
• Retries that honour Retry-After on 429 and on 409 IDEMPOTENCY_IN_FLIGHT, and jittered backoff on 5xx and network failures — except a chat turn's 5xx, which is never retried, because the turn may already have run and been billed.
• Typed errors carrying the HTTP status, error.code, error.details, the request_id to quote to support, Retry-After and, for a failed chat turn, the chatbot's fallback reply. Each status has its own class — bad request, authentication, payment required, permission denied, not found, conflict, unprocessable, rate limited, server error — plus connection, timeout and invalid-response errors, and an ErrorCode list of every documented code.
• Webhook verification — Agentency.webhooks.constructEvent in TypeScript, construct_event in Python. Both check the timestamp and accept either signature during a rotation.

chat.stream yields one object per frame: event (the SSE event name, message for content), data (the raw text) and json (the parsed payload, or empty when data is not JSON, as for [DONE]). The frame order is the one described in Chat: content, an optional final_text that replaces the streamed text, [DONE], then metadata. A valid options frame also carries a typed options field.

A timeout bounds the wait for the response and every gap between frames; the server's heartbeats keep a slow answer alive. Stopping early releases the connection at once (break in TypeScript, leaving the with block in Python). If the connection drops mid-answer, send the same turn again with the same idempotency key: a turn still running is waited for, and a finished one is neither run nor billed again — the stream yields one replay frame with its summary instead.

For a language we do not ship, generate one from the spec. It is the same source the official SDKs are built from:

It is OpenAPI 3.1 and includes the required scope per operation and the webhook payloads, so a generated client can surface both.

If you go this way, the four things worth implementing by hand are the ones the official clients do for you: Idempotency-Key on writes, Retry-After backoff, error-code typing, and webhook signature verification.

• Chat — the endpoints the SDKs wrap most.
• Webhooks — what the verification helpers are for.
• Status and the spec — where to get the document.