API Reference

The Theazo REST API is the foundation of the TypeScript SDK. Use it directly if you are integrating from a language without an official SDK, or building your own tooling.

Base URL

https://api.theazo.com/v1

Authentication

Pass your API key as a Bearer token in every request. Live keys begin with th_live_; test keys with th_test_. Test keys return mocked responses and never provision real compute.

terminal

curl https://api.theazo.com/v1/sessions \
  -H "Authorization: Bearer th_live_..."

API keys are sensitive credentials. Never expose them in client-side code or commit them to source control. Use environment variables and access them server-side only.

Error format

All errors return a consistent JSON envelope. The HTTP status code reflects the error category. Always check error.code for programmatic handling.

error.json

// HTTP 429
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 2 seconds.",
    "details": { "retryAfter": 2 },
    "requestId": "req_01HX3K2..."
  }
}

Error codes

unauthorizedHTTP 401Missing or invalid API key.

forbiddenHTTP 403API key valid but lacks permission for this action.

not_foundHTTP 404The requested resource does not exist.

conflictHTTP 409Operation conflicts with current state (e.g. resuming a non-paused agent).

unprocessable_entityHTTP 422Request body failed validation. See details for field-level errors.

rate_limitedHTTP 429Request rate exceeded. Check Retry-After header.

session_limit_exceededHTTP 402Session cost, agent, or compute limit reached.

provider_errorHTTP 502Upstream compute provider returned an error.

timeoutHTTP 504Agent exec() exceeded the 120-second timeout.

internal_errorHTTP 500Unexpected server error. The requestId helps with support.

Sessions

Sessions provide per-user isolation. Every agent runs inside exactly one session. Cost tracking, compute limits, and billing data are scoped to a session.

POST/v1/sessions

Create a new session. Returns immediately with the session object. Agents can be added to this session right away.

Parameters

userIdstringrequiredYour application's user identifier. Opaque to Theazo — use whatever you use internally.

limitsobjectCost and concurrency limits for this session.

limits.maxCostobject{ amount: number (cents), currency: string, period: 'session'|'day'|'month' }

limits.maxAgentsnumberMaximum concurrent agents allowed in this session.

limits.maxComputeMinutesnumberTotal compute minutes before the session is auto-paused.

metadataobjectArbitrary key-value pairs stored with the session. Returned on list.

Response

Session

Example

bash

curl -X POST https://api.theazo.com/v1/sessions \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "limits": {
      "maxCost": { "amount": 500, "currency": "usd", "period": "day" },
      "maxAgents": 3
    },
    "metadata": { "plan": "pro" }
  }'

POST/v1/sessions/by-user/:userId

Idempotent get-or-create. If a session already exists for this userId it is returned unchanged. If not, a new one is created with the provided options. Safe to call on every request without tracking session IDs yourself.

Parameters

userIdstringrequiredURL parameter. Your application's user identifier.

limitsobjectApplied only when creating a new session. Ignored if a session already exists.

metadataobjectApplied only on creation.

Response

Session

Example

bash

curl -X POST https://api.theazo.com/v1/sessions/by-user/user_123 \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "limits": {
      "maxCost": { "amount": 1000, "currency": "usd", "period": "month" }
    }
  }'

Agents

Agents are isolated compute environments within a session. Create an agent, then run tasks against it. An agent exists until explicitly terminated or until its session ends.

POST/v1/sessions/:id/agents

Create a new agent inside a session. Provisions compute immediately. The agent is ready to accept tasks once status is 'idle'.

Parameters

computeobjectOverride compute provider for this agent. Defaults to platform config.

compute.providerstring'e2b' | 'fly' | 'docker'

modelobjectModel configuration for orchestrator mode.

model.idstringModel ID, e.g. 'claude-3-5-sonnet-20241022'.

browserbooleanAttach a headless browser to the sandbox. Default: false.

instructionsstringSystem-level instructions prepended to every task prompt.

toolsstring[]Built-in tool names to enable: 'web_search', 'http_request', 'write_file', etc.

timeoutnumberMax seconds an agent run may take before being forcibly terminated. Default: 300.

Response

Agent

Example

bash

curl -X POST https://api.theazo.com/v1/sessions/ses_01HX.../agents \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "browser": true,
    "tools": ["web_search", "write_file"],
    "instructions": "You are a research assistant. Be concise.",
    "timeout": 120
  }'

POST/v1/agents/:id/run

Run a task asynchronously. Returns 202 immediately with a taskId. The agent loop (model → tool → model) runs in the background. Poll GET /v1/agents/:id for status or stream events via SSE.

Parameters

taskstringrequiredThe task prompt to send to the agent.

Response

{ taskId: string }

Example

bash

curl -X POST https://api.theazo.com/v1/agents/agt_01HX.../run \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "task": "Summarize the top 5 AI research papers from this week" }'

# Response:
# { "taskId": "task_01HX...", "agentId": "agt_01HX..." }

POST/v1/agents/:id/exec

Execute code directly inside the sandbox, synchronously. The request blocks until the code finishes or the 120-second timeout is reached. Intended for infra-only mode: run your own agent framework (LangGraph, CrewAI) inside Theazo's isolated compute.

Parameters

langstringrequired'python' | 'typescript' | 'bash'

codestringrequiredCode to execute inside the sandbox.

Response

ExecResult

Example

bash

curl -X POST https://api.theazo.com/v1/agents/agt_01HX.../exec \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "lang": "python",
    "code": "print(2 + 2)"
  }'

# Response:
# { "stdout": "4\n", "stderr": "", "exitCode": 0, "durationMs": 312 }

GET/v1/agents/:id/stream

Stream agent events as Server-Sent Events (SSE). Connect before calling /run to receive all events from the start. Each event includes a type (thinking, tool_call, tool_result, output, error) and payload.

Response

text/event-stream

Example

bash

curl -N https://api.theazo.com/v1/agents/agt_01HX.../stream \
  -H "Authorization: Bearer th_live_..." \
  -H "Accept: text/event-stream"

# Stream output:
# event: thinking
# data: {"text":"I'll search for recent AI papers..."}
#
# event: tool_call
# data: {"tool":"web_search","input":{"query":"AI papers 2025"}}
#
# event: output
# data: {"text":"Here are the top 5...","cost":{"amount":12,"currency":"usd"}}

POST/v1/agents/:id/pause

Pause a running agent. The agent completes its current tool call then suspends. State is snapshotted. Resume with /resume.

Response

Agent

Example

bash

curl -X POST https://api.theazo.com/v1/agents/agt_01HX.../pause \
  -H "Authorization: Bearer th_live_..."

POST/v1/agents/:id/resume

Resume a paused agent. The agent restores its snapshot and continues from where it left off.

Response

Agent

Example

bash

curl -X POST https://api.theazo.com/v1/agents/agt_01HX.../resume \
  -H "Authorization: Bearer th_live_..."

POST/v1/agents/:id/terminate

Permanently terminate an agent. Compute is released, snapshot is deleted. This is irreversible.

Response

{ ok: true }

Example

bash

curl -X POST https://api.theazo.com/v1/agents/agt_01HX.../terminate \
  -H "Authorization: Bearer th_live_..."

Usage

GET/v1/usage/summary

Return aggregated usage for the current billing period: compute minutes, model tokens, storage, and total cost. Optionally filter by date range.

Parameters

fromstringISO 8601 start date. Defaults to start of current billing period.

untilstringISO 8601 end date. Defaults to now.

Response

UsageSummary

Example

bash

curl "https://api.theazo.com/v1/usage/summary?from=2025-05-01" \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "period": { "from": "2025-05-01T00:00:00Z", "until": "2025-05-06T14:00:00Z" },
#   "compute": { "minutes": 142, "cost": { "amount": 710, "currency": "usd" } },
#   "models":  { "inputTokens": 1240000, "outputTokens": 380000,
#                "cost": { "amount": 830, "currency": "usd" } },
#   "storage": { "gb": 0.4, "cost": { "amount": 4, "currency": "usd" } },
#   "total":   { "amount": 1544, "currency": "usd" }
# }

Providers

Configure compute providers for your platform. Theazo routes agent compute to whatever backend you configure — E2B, Fly.io, or a custom webhook. You can configure multiple providers and set a default.

GET/v1/providers

List all configured compute providers for your platform.

Response

Provider[]

Example

bash

curl https://api.theazo.com/v1/providers \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "data": [
#     { "provider": "e2b", "isDefault": true, "status": "active", "createdAt": "2025-05-01T..." },
#     { "provider": "fly", "isDefault": false, "status": "active", "createdAt": "2025-05-03T..." }
#   ]
# }

POST/v1/providers

Configure a new compute provider. Credentials are encrypted at rest. Set isDefault to make this the default provider for new agents.

Parameters

providerstringrequired'e2b' | 'fly' | 'webhook'

credentialsobjectrequiredProvider-specific credentials (API keys, endpoints). Encrypted at rest.

isDefaultbooleanSet as the default provider. Default: false.

Response

Provider

Example

bash

curl -X POST https://api.theazo.com/v1/providers \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "e2b",
    "credentials": { "apiKey": "e2b_..." },
    "isDefault": true
  }'

DELETE/v1/providers/:provider

Remove a configured provider. Fails if the provider has active agents.

Response

{ ok: true }

Example

bash

curl -X DELETE https://api.theazo.com/v1/providers/fly \
  -H "Authorization: Bearer th_live_..."

Secrets

Store encrypted credentials that agents can access at runtime. Secrets are encrypted with AES-256-GCM and can be scoped to the entire organization or to a specific session.

POST/v1/secrets

Set a secret. If a secret with the same name and scope already exists, it is overwritten.

Parameters

namestringrequiredSecret name. Alphanumeric, underscores, and hyphens only.

valuestringrequiredSecret value. Encrypted at rest — never returned by the API after creation.

sessionIdstringScope to a specific session. Omit for org-wide secrets.

Response

{ name: string, scope: string, createdAt: string }

Example

bash

curl -X POST https://api.theazo.com/v1/secrets \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPENAI_API_KEY",
    "value": "sk-..."
  }'

GET/v1/secrets

List secrets (metadata only). Values are never returned.

Parameters

sessionIdstringFilter to secrets scoped to this session. Omit for org-wide.

Response

SecretMetadata[]

Example

bash

curl https://api.theazo.com/v1/secrets \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "data": [
#     { "name": "OPENAI_API_KEY", "scope": "org", "createdAt": "2025-05-01T..." },
#     { "name": "DB_PASSWORD", "scope": "ses_01HX...", "createdAt": "2025-05-02T..." }
#   ]
# }

DELETE/v1/secrets/:name

Delete a secret by name. If the secret is session-scoped, pass the sessionId as a query parameter.

Parameters

sessionIdstringRequired if deleting a session-scoped secret.

Response

{ ok: true }

Example

bash

curl -X DELETE "https://api.theazo.com/v1/secrets/DB_PASSWORD?sessionId=ses_01HX..." \
  -H "Authorization: Bearer th_live_..."

Agent Definitions

Agent definitions are reusable templates for agent configuration. Define instructions, tools, model, and compute settings once, then create agents from the definition. Definitions are versioned — updates create a new version automatically.

POST/v1/agent-definitions

Create a new agent definition. Returns the definition with version 1.

Parameters

namestringrequiredHuman-readable name for this definition.

instructionsstringSystem-level instructions for agents created from this definition.

toolsstring[]Built-in tool names to enable.

modelobjectModel configuration: { id, maxTokens, temperature }.

computeobjectCompute configuration: { provider, timeout }.

metadataobjectArbitrary key-value pairs.

Response

AgentDefinition

Example

bash

curl -X POST https://api.theazo.com/v1/agent-definitions \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "instructions": "You are a research assistant. Be thorough and cite sources.",
    "tools": ["web_search", "write_file"],
    "model": { "id": "claude-sonnet-4-20250514" }
  }'

GET/v1/agent-definitions

List all agent definitions. Archived definitions are excluded by default.

Parameters

includeArchivedbooleanInclude archived definitions. Default: false.

Response

AgentDefinition[]

Example

bash

curl https://api.theazo.com/v1/agent-definitions \
  -H "Authorization: Bearer th_live_..."

GET/v1/agent-definitions/:id

Get a single agent definition with its latest version details.

Response

AgentDefinition

Example

bash

curl https://api.theazo.com/v1/agent-definitions/adef_01HX... \
  -H "Authorization: Bearer th_live_..."

PUT/v1/agent-definitions/:id

Update a definition. Creates a new version — existing agents are not affected. The version number increments automatically.

Parameters

instructionsstringUpdated system instructions.

toolsstring[]Updated tool list.

modelobjectUpdated model configuration.

computeobjectUpdated compute configuration.

Response

AgentDefinition

Example

bash

curl -X PUT https://api.theazo.com/v1/agent-definitions/adef_01HX... \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": { "id": "claude-sonnet-4-20250514" },
    "tools": ["web_search", "write_file", "http_request"]
  }'

DELETE/v1/agent-definitions/:id

Archive a definition. It will no longer appear in list results and cannot be used to create new agents. Existing agents are not affected.

Response

{ ok: true }

Example

bash

curl -X DELETE https://api.theazo.com/v1/agent-definitions/adef_01HX... \
  -H "Authorization: Bearer th_live_..."

Billing

Query usage and cost data for your platform. All cost amounts are in integer cents. Use these endpoints to build billing dashboards, set alerts, or reconcile invoices.

GET/v1/billing/usage

Usage summary for the current or specified billing period. Returns total costs, compute minutes, model calls, and storage.

Parameters

fromstringISO 8601 start date. Defaults to current billing period start.

untilstringISO 8601 end date. Defaults to now.

Response

BillingUsage

Example

bash

curl "https://api.theazo.com/v1/billing/usage?from=2025-05-01" \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "period": { "from": "2025-05-01T00:00:00Z", "until": "2025-05-06T14:00:00Z" },
#   "totalCost": { "amount": 4200, "currency": "usd" },
#   "computeMinutes": 310,
#   "modelCalls": 1842,
#   "sessions": 47,
#   "agents": 126
# }

GET/v1/billing/usage/daily

Daily cost time series. Returns one entry per day within the specified range.

Parameters

fromstringISO 8601 start date. Defaults to 30 days ago.

untilstringISO 8601 end date. Defaults to now.

Response

DailyCost[]

Example

bash

curl "https://api.theazo.com/v1/billing/usage/daily?from=2025-05-01&until=2025-05-07" \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "data": [
#     { "date": "2025-05-01", "cost": { "amount": 580, "currency": "usd" } },
#     { "date": "2025-05-02", "cost": { "amount": 720, "currency": "usd" } }
#   ]
# }

GET/v1/billing/usage/users

Per-user cost breakdown. Returns costs aggregated by userId across all sessions.

Parameters

fromstringISO 8601 start date.

untilstringISO 8601 end date.

limitnumberMax users to return. Default: 50.

Response

UserCost[]

Example

bash

curl "https://api.theazo.com/v1/billing/usage/users?from=2025-05-01&limit=10" \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "data": [
#     { "userId": "user_123", "cost": { "amount": 1200, "currency": "usd" }, "sessions": 5, "agents": 12 },
#     { "userId": "user_456", "cost": { "amount": 890, "currency": "usd" }, "sessions": 3, "agents": 8 }
#   ]
# }

GET/v1/billing/usage/models

Per-model cost breakdown. Returns costs aggregated by model ID.

Parameters

fromstringISO 8601 start date.

untilstringISO 8601 end date.

Response

ModelCost[]

Example

bash

curl "https://api.theazo.com/v1/billing/usage/models?from=2025-05-01" \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "data": [
#     { "model": "claude-sonnet-4-20250514", "calls": 1200, "inputTokens": 980000, "outputTokens": 310000, "cost": { "amount": 2100, "currency": "usd" } },
#     { "model": "gpt-4o", "calls": 642, "inputTokens": 520000, "outputTokens": 180000, "cost": { "amount": 1400, "currency": "usd" } }
#   ]
# }

Workflows (additional)

Additional endpoints for workflow estimation and streaming. See the POST /v1/workflows and GET /v1/workflows CRUD endpoints in the SDK reference.

POST/v1/workflows/:id/estimate

Estimate the cost of running a workflow before executing it. Returns estimated compute minutes, model calls, and total cost based on the workflow's step graph and historical averages.

Parameters

inputobjectInput data for the workflow. Used to determine which conditional branches will execute.

Response

WorkflowEstimate

Example

bash

curl -X POST https://api.theazo.com/v1/workflows/wf_01HX.../estimate \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "input": { "url": "https://example.com" } }'

# Response:
# {
#   "steps": 4,
#   "estimatedMinutes": 8,
#   "estimatedCost": { "amount": 120, "currency": "usd" },
#   "confidence": "medium"
# }

GET/v1/workflow-runs/:runId/stream

SSE stream of workflow execution events. Each event includes the step name, status, and output as steps complete.

Response

text/event-stream

Example

bash

curl -N https://api.theazo.com/v1/workflow-runs/wfr_01HX.../stream \
  -H "Authorization: Bearer th_live_..." \
  -H "Accept: text/event-stream"

# Stream output:
# event: step:start
# data: {"step":"scrape","index":0}
#
# event: step:complete
# data: {"step":"scrape","index":0,"output":{"html":"..."},"durationMs":2100}
#
# event: workflow:complete
# data: {"output":{...},"cost":{"amount":95,"currency":"usd"}}

Fleets (additional)

Additional streaming endpoint for fleets. See the CRUD endpoints in the SDK reference.

GET/v1/fleets/:id/stream

SSE stream of fleet execution. Emits events as individual agents within the fleet start, complete, or fail.

Response

text/event-stream

Example

bash

curl -N https://api.theazo.com/v1/fleets/flt_01HX.../stream \
  -H "Authorization: Bearer th_live_..." \
  -H "Accept: text/event-stream"

# Stream output:
# event: agent:start
# data: {"agentId":"agt_01HX...","index":0,"task":"Scrape page 1"}
#
# event: agent:complete
# data: {"agentId":"agt_01HX...","index":0,"output":"...","cost":{"amount":8,"currency":"usd"}}
#
# event: fleet:complete
# data: {"completed":10,"failed":0,"totalCost":{"amount":82,"currency":"usd"}}

Schedules

Create cron-based schedules that automatically run agents or workflows on a recurring basis. Schedules use standard cron expressions and run in UTC.

POST/v1/schedules

Create a new schedule. The first run occurs at the next matching cron time.

Parameters

namestringrequiredHuman-readable name for this schedule.

cronstringrequiredCron expression (5 fields, UTC). e.g. '0 9 * * 1-5' for weekdays at 9am.

actionobjectrequiredWhat to run: { type: 'agent-run' | 'workflow-run', config: { ... } }.

metadataobjectArbitrary key-value pairs.

Response

Schedule

Example

bash

curl -X POST https://api.theazo.com/v1/schedules \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily report",
    "cron": "0 9 * * 1-5",
    "action": {
      "type": "agent-run",
      "config": {
        "definitionId": "adef_01HX...",
        "task": "Generate the daily metrics report"
      }
    }
  }'

GET/v1/schedules

List all schedules. Returns active and paused schedules.

Parameters

statusstringFilter by status: 'active' | 'paused'. Omit for all.

Response

Schedule[]

Example

bash

curl https://api.theazo.com/v1/schedules \
  -H "Authorization: Bearer th_live_..."

PATCH/v1/schedules/:id

Update a schedule's cron expression, action, or name.

Parameters

namestringUpdated name.

cronstringUpdated cron expression.

actionobjectUpdated action configuration.

Response

Schedule

Example

bash

curl -X PATCH https://api.theazo.com/v1/schedules/sched_01HX... \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "cron": "0 8 * * *" }'

DELETE/v1/schedules/:id

Delete a schedule. All future runs are cancelled.

Response

{ ok: true }

Example

bash

curl -X DELETE https://api.theazo.com/v1/schedules/sched_01HX... \
  -H "Authorization: Bearer th_live_..."

POST/v1/schedules/:id/pause

Pause a schedule. No runs will be triggered until resumed.

Response

Schedule

Example

bash

curl -X POST https://api.theazo.com/v1/schedules/sched_01HX.../pause \
  -H "Authorization: Bearer th_live_..."

POST/v1/schedules/:id/resume

Resume a paused schedule. The next run occurs at the next matching cron time.

Response

Schedule

Example

bash

curl -X POST https://api.theazo.com/v1/schedules/sched_01HX.../resume \
  -H "Authorization: Bearer th_live_..."

Triggers

Webhook triggers let external systems start agent runs or workflows. Each trigger gets a unique URL. Incoming requests are verified with HMAC signatures.

POST/v1/triggers

Create a webhook trigger. Returns a unique trigger URL and signing secret.

Parameters

namestringrequiredHuman-readable name for this trigger.

actionobjectrequiredWhat to run: { type: 'agent-run' | 'workflow-run', config: { ... } }.

Response

Trigger

Example

bash

curl -X POST https://api.theazo.com/v1/triggers \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub push handler",
    "action": {
      "type": "agent-run",
      "config": {
        "definitionId": "adef_01HX...",
        "task": "Review the pushed code changes"
      }
    }
  }'

# Response includes:
# {
#   "id": "trg_01HX...",
#   "url": "https://api.theazo.com/v1/triggers/trg_01HX.../fire",
#   "signingSecret": "whsec_...",
#   ...
# }

GET/v1/triggers

List all triggers.

Response

Trigger[]

Example

bash

curl https://api.theazo.com/v1/triggers \
  -H "Authorization: Bearer th_live_..."

DELETE/v1/triggers/:id

Delete a trigger. The trigger URL stops accepting requests immediately.

Response

{ ok: true }

Example

bash

curl -X DELETE https://api.theazo.com/v1/triggers/trg_01HX... \
  -H "Authorization: Bearer th_live_..."

POST/v1/triggers/:id/fire

Fire a trigger. This is the public endpoint — no Bearer auth required. Requests must include a valid HMAC signature in the X-Theazo-Signature header. The request body is passed as input to the action.

Response

{ taskId: string }

Example

bash

curl -X POST https://api.theazo.com/v1/triggers/trg_01HX.../fire \
  -H "Content-Type: application/json" \
  -H "X-Theazo-Signature: sha256=..." \
  -d '{ "ref": "refs/heads/main", "commits": [...] }'

# Response:
# { "taskId": "task_01HX..." }

Channels

Channels provide embeddable chat interfaces backed by agents. Create a channel, then use the public message and stream endpoints to build chat UIs without exposing your API key.

POST/v1/channels

Create a chat channel. Returns the channel with a public ID that can be used in client-side code.

Parameters

namestringrequiredChannel name.

definitionIdstringAgent definition to back this channel.

instructionsstringSystem instructions for the channel's agent.

metadataobjectArbitrary key-value pairs.

Response

Channel

Example

bash

curl -X POST https://api.theazo.com/v1/channels \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Chat",
    "instructions": "You are a helpful support agent for Acme Corp."
  }'

GET/v1/channels

List all channels.

Response

Channel[]

Example

bash

curl https://api.theazo.com/v1/channels \
  -H "Authorization: Bearer th_live_..."

POST/v1/channels/:id/messages

Send a message to a channel. This is a public endpoint — no Bearer auth required. The channel ID serves as the access token. Returns the agent's response.

Parameters

contentstringrequiredThe user's message text.

threadIdstringThread ID for multi-turn conversations. Omit to start a new thread.

Response

Message

Example

bash

curl -X POST https://api.theazo.com/v1/channels/ch_01HX.../messages \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "threadId": "thr_01HX..."
  }'

GET/v1/channels/:id/messages

Get messages for a channel. Public endpoint — no auth required. Returns messages in chronological order.

Parameters

threadIdstringFilter to a specific thread.

limitnumberMax messages to return. Default: 50.

cursorstringPagination cursor.

Response

Message[]

Example

bash

curl "https://api.theazo.com/v1/channels/ch_01HX.../messages?threadId=thr_01HX...&limit=20"

GET/v1/channels/:id/stream

SSE stream of channel messages. Public endpoint — no auth required. Stays open and emits new messages as they are sent and received.

Parameters

threadIdstringFilter to a specific thread.

Response

text/event-stream

Example

bash

curl -N "https://api.theazo.com/v1/channels/ch_01HX.../stream?threadId=thr_01HX..."

# Stream output:
# event: message
# data: {"role":"user","content":"How do I reset my password?"}
#
# event: message
# data: {"role":"assistant","content":"To reset your password, go to Settings..."}

Pagination

List endpoints return cursor-based pages. Pass the cursor from the previous response to fetch the next page. A missing nextCursor means you are on the last page.

pagination.txt

// First page
GET /v1/sessions?limit=25

// Response
{
  "data": [...],
  "nextCursor": "cur_01HX3K...",
  "hasMore": true
}

// Next page
GET /v1/sessions?limit=25&cursor=cur_01HX3K...

Rate limits

Rate limits are applied per API key using a sliding window. Limits vary by plan. When exceeded, the API returns HTTP 429 with aRetry-After header indicating how many seconds to wait.

Free60 req / minDevelopment and testing only.

Cloud300 req / minProduction workloads.

Team1,000 req / minHigh-throughput applications.

EnterpriseCustomDedicated limits negotiated per contract.