SDKs

Official clients for TypeScript and Python. They wrap the same /v1 surface these docs describe, and their type definitions are generated from the same OpenAPI document — so they cannot describe an endpoint that does not exist.

Installing

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

bash

npm install ./sdks/typescript

bash

pip install ./sdks/python

Getting started

curl

# No SDK needed — every endpoint is ordinary REST.
curl https://api.agentency.com/v1/me \
  -H "Authorization: Bearer <YOUR_KEY>"

What they handle for you

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 mutations, so a retry cannot double-write.
Retries that honour Retry-After, with exponential backoff and jitter.
Typed errors carrying error.code and request_id.
Webhook verification — webhooks.constructEvent in TypeScript, webhooks.construct_event in Python. Both check the timestamp and accept either signature during a rotation.

Use the webhook helper

Signature verification has two easy mistakes: parsing the body before signing it, and keeping only one `v1` value. The helpers get both right and are tested against the same fixture the server signs with.

Streaming

curl

curl -N -X POST https://api.agentency.com/v1/chat/stream \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"chatbot_id": 1, "message": "Do you ship to Ireland?"}'

Browser use

The browser build refuses live keys

`@agentency/sdk` throws if it is constructed with an `agy_live_` key in a browser. That is a guard rail, not a security boundary — a test key in a browser is still visible to anyone who opens devtools. Call the API from your server, and use the widget for anything in a page.

Generating your own client

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

bash

curl https://api.agentency.com/v1/openapi.json -o agentency.json

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.

What's next

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

SDKs

Installing

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

bash

npm install ./sdks/typescript

bash

pip install ./sdks/python

Getting started

curl

# No SDK needed — every endpoint is ordinary REST.
curl https://api.agentency.com/v1/me \
  -H "Authorization: Bearer <YOUR_KEY>"

What they handle for you

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 mutations, so a retry cannot double-write.
Retries that honour Retry-After, with exponential backoff and jitter.
Typed errors carrying error.code and request_id.
Webhook verification — webhooks.constructEvent in TypeScript, webhooks.construct_event in Python. Both check the timestamp and accept either signature during a rotation.

Use the webhook helper

Streaming

curl

curl -N -X POST https://api.agentency.com/v1/chat/stream \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"chatbot_id": 1, "message": "Do you ship to Ireland?"}'

Browser use

The browser build refuses live keys

Generating your own client

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

bash

curl https://api.agentency.com/v1/openapi.json -o agentency.json

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

What's next

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