TheazoTheazo
Get Started

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

userIdstringrequiredEnd-user this session belongs to.
environment'production' | 'staging' | 'development'Isolation environment. Default: production.
limitsobjectPer-session cost / agent / compute / duration ceilings.
metadataRecord<string, string>Arbitrary key-value metadata attached to the session.

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

compute'python' | 'node' | 'go'Sandbox runtime. Default: python.
browserbooleanProvision a sandbox with a browser. Requires a browser-capable E2B template (E2B_BROWSER_TEMPLATE); agent creation fails with a clear error if none is configured, since the default sandbox has neither Chromium nor the memory to run it. Default: false.
storagestringPersistent storage to attach, e.g. "1GB". NOT SUPPORTED by any current provider — E2B sandboxes are ephemeral, so this is rejected at provision time rather than ignored.
gpustringGPU type to attach, e.g. "a100". Omit for CPU-only.
modelstringModel ID, e.g. 'anthropic/claude-sonnet'. Default: anthropic/claude-sonnet.
instructionsstringSystem prompt / behavioral instructions for the agent.
toolsstring[]Names of tools the agent is allowed to call.
timeoutstringMax wall-clock time for the run, e.g. "30s", "5m", "2h". Bounds the sandbox lifetime; capped at 24h. Invalid values are rejected. Default 15m.
costCapobjectHard spend ceiling for this agent (integer cents + currency).
providerstringCompute provider to run on (e.g. "e2b"). Omit to use the platform default.
providerFallbackstringProvider to fall back to if the primary is unavailable.
regionstringPreferred region for the sandbox.
approvalsobjectHuman-in-the-loop approval policy for sensitive actions.
knowledgeboolean | stringAttach knowledge: true for the session default collection, or a collection name/ID.
metadataobjectMetadata extraction rules + custom key-value pairs.
guardrailsobjectContent / PII / prompt-injection guardrails applied to this agent.
lifecycleobjectAuto-pause and failure-handling policy. NOT ENFORCED yet — supplying it returns 501 rather than accepting a policy that would not be applied.
definitionstringAgent-definition name or ID to instantiate this agent from.
overridesRecord<string, unknown>Field overrides applied on top of the referenced definition’s config.
secretsstring[]Names of secrets to inject into the agent environment.
mcpstring[] | '*'MCP connection IDs or names to attach, or '*' to attach all of them.

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 '{
    "tools": ["exec_code", "write_file"],
    "instructions": "You are a research assistant. Be concise.",
    "timeout": "120s"
  }'
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

languagestringrequiredLanguage to run: '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 '{
    "language": "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":"exec_code","input":{"code":"import pandas as pd..."}}
#
# 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_..."

Snapshots

A snapshot is a captured agent state — created when you pause an agent (see POST /v1/agents/:id/pause). These endpoints list, inspect, resume, and delete them. Most workflows use snapshots indirectly through agent pause/resume and long-running checkpoints rather than calling these directly.

GET/v1/snapshots

List snapshots for your platform, newest first.

Parameters

sessionIdstringFilter to snapshots from this session.
agentIdstringFilter to snapshots from this agent.
statestringFilter by state (e.g. 'ready', 'creating').

Response

{ data: Snapshot[] }

Example

bash
curl "https://api.theazo.com/v1/snapshots?agentId=agt_01HX..." \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "data": [
#     {
#       "id": "snap_01HX...", "agentId": "agt_01HX...", "sessionId": "ses_01HX...",
#       "provider": "e2b", "type": "pause", "sizeBytes": 262144000,
#       "state": "ready", "createdAt": "2026-08-06T10:00:00Z"
#     }
#   ]
# }
GET/v1/snapshots/:id

Get a single snapshot by id.

Response

Snapshot

Example

bash
curl https://api.theazo.com/v1/snapshots/snap_01HX... \
  -H "Authorization: Bearer th_live_..."
POST/v1/snapshots/:id/resume

Boot a new agent from a snapshot. Restores natively on the same provider, or via filesystem restore when resuming onto a different provider. The snapshot must be in the 'ready' state.

Parameters

providerstringTarget provider. Defaults to the snapshot's original provider.
regionstringTarget region. Default: 'us-east-1'.

Response

{ agentId: string; provider: string; region: string; resumeLevel: 'native' | 'filesystem'; status: 'booting' }

Example

bash
curl -X POST https://api.theazo.com/v1/snapshots/snap_01HX.../resume \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "provider": "fly", "region": "us-east-1" }'

# Response (201):
# { "agentId": "agt_new...", "provider": "fly", "region": "us-east-1",
#   "resumeLevel": "filesystem", "status": "booting" }
DELETE/v1/snapshots/:id

Delete a snapshot. Its stored state is released and it can no longer be resumed.

Response

{ ok: true }

Example

bash
curl -X DELETE https://api.theazo.com/v1/snapshots/snap_01HX... \
  -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 configured (BYOI) providers for your platform. A provider not in this list is running in Theazo-managed mode.

Response

ProviderConfig[]

Example

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

# Response:
# {
#   "data": [
#     { "provider": "e2b", "enabled": true, "credentialRef": "my_e2b_key", "config": null, "createdAt": "2025-05-01T..." }
#   ]
# }
PUT/v1/providers/:provider

Configure a compute/model provider (BYOI). The provider name is the URL path param (e2b, fly, anthropic, webhook, …). The API key is not sent inline — pass credentialRef, the name of a secret created via POST /v1/secrets.

Parameters

credentialRefstringrequiredName of the secret (created via POST /v1/secrets) that holds the provider API key.
configRecord<string, unknown>Provider-specific config, e.g. { endpoint } for webhook/custom compute providers.
enabledbooleanWhether this provider is active. Default: true.

Response

{ ok: true, provider: string, mode: 'byoi' }

Example

bash
curl -X PUT https://api.theazo.com/v1/providers/e2b \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "credentialRef": "my_e2b_key"
  }'
DELETE/v1/providers/:provider

Remove BYOI config for a provider, reverting it to Theazo-managed mode. Does not check for in-flight agents on that provider — the change applies to future provisioning.

Response

{ ok: true, provider: string, mode: 'managed' }

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 one or more org-wide secrets. The body is a flat JSON object of secret name → value pairs; existing names are overwritten. Values are encrypted at rest (AES-256-GCM) and never returned after creation.

Response

{ ok: true, count: number }

Example

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

List org-wide secrets (metadata only — name and createdAt, never values).

Response

{ name: string; createdAt: string }[]

Example

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

# Response:
# { "data": [ { "name": "OPENAI_API_KEY", "createdAt": "2025-05-01T..." } ] }
DELETE/v1/secrets/:name

Delete an org-wide secret by name.

Response

{ ok: true }

Example

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

Session-scoped secrets are a separate set of routes, not a query parameter on the org-wide endpoints above — POST /GET /v1/sessions/:id/secrets and DELETE /v1/sessions/:id/secrets/:name. Same request/ response shapes as above, scoped to that session instead of the whole platform.

session-scoped-secrets.sh
curl -X POST https://api.theazo.com/v1/sessions/ses_.../secrets \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "DB_PASSWORD": "..." }'

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

curl -X DELETE https://api.theazo.com/v1/sessions/ses_.../secrets/DB_PASSWORD \
  -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 name for the blueprint.
descriptionstringWhat this agent does.
compute'python' | 'node' | 'go'Sandbox runtime. Default: python.
modelstringModel identifier, e.g. anthropic/claude-sonnet.
systemPromptstringSystem prompt applied to every agent created from this blueprint.
toolsstring[]Built-in / custom tool names available to the agent.
browserbooleanProvision a sandbox with a browser. Requires a browser-capable E2B template (E2B_BROWSER_TEMPLATE); agent creation fails with a clear error if none is configured, since the default sandbox has neither Chromium nor the memory to run it. Default: false.
timeoutstringMax wall-clock time for a run started from this definition, e.g. "30s", "5m", "2h". Bounds the sandbox lifetime; capped at 24h. Invalid values are rejected. Default 15m.
configobjectModel config (temperature, maxTokens).

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",
    "systemPrompt": "You are a research assistant. Be thorough and cite sources.",
    "tools": ["exec_code", "write_file"],
    "model": "anthropic/claude-sonnet"
  }'
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

systemPromptstringNew system prompt.
toolsstring[]New tool list.
modelstringNew model.
compute'python' | 'node' | 'go'New sandbox runtime.
browserbooleanProvision a sandbox with a browser. Requires a browser-capable E2B template (E2B_BROWSER_TEMPLATE); agent creation fails with a clear error if none is configured, since the default sandbox has neither Chromium nor the memory to run it. Default: false.
timeoutstringNew max run duration, e.g. "10m".
configobjectNew model config.
changelogstringNote describing this version.

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": "anthropic/claude-sonnet",
    "tools": ["exec_code", "write_file", "read_file"]
  }'
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_..."
GET/v1/agent-definitions/:id/versions

List all versions of a definition, newest first. Each PUT update creates a new version rather than overwriting the current one.

Response

{ version: number, createdAt: string, changelog: string, createdBy: string }[]

Example

bash
curl https://api.theazo.com/v1/agent-definitions/adef_01HX.../versions \
  -H "Authorization: Bearer th_live_..."
POST/v1/agent-definitions/:id/rollback

Point the definition's current version back at an earlier version. Does not delete the versions in between — they remain in history and can be rolled forward to again.

Parameters

versionnumberrequiredThe version number to roll back to. Must already exist in this definition's version history.

Response

{ ok: true, version: number }

Example

bash
curl -X POST https://api.theazo.com/v1/agent-definitions/adef_01HX.../rollback \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "version": 2 }'
POST/v1/agent-definitions/:id/duplicate

Create a new, independent definition (version 1) seeded from this definition's latest version. Changes to the copy never affect the original.

Parameters

namestringrequiredName for the new definition.

Response

{ id: string, name: string }

Example

bash
curl -X POST https://api.theazo.com/v1/agent-definitions/adef_01HX.../duplicate \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Research Assistant (copy)" }'

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.

Every endpoint below takes a period query param (not from/until — there's no arbitrary date-range support today), one of today, week, last_7_days, last_30_days, month (default).

GET/v1/usage/summary

Usage summary for the platform: total cost split into what Theazo billed you vs. what you paid providers directly (BYOI), plus active session/agent counts.

Parameters

periodstringSee period values above. Default: month.
environmentstringFilter to 'production' or 'development'. Omit for all.

Response

UsageSummary

Example

bash
curl "https://api.theazo.com/v1/usage/summary?period=last_30_days" \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "totalCost": { "amount": 4200, "currency": "usd" },
#   "activeSessions": 12,
#   "runningAgents": 3,
#   "topUser": { "userId": "user_123", "cost": { "amount": 890, "currency": "usd" } },
#   "environment": "production",
#   "theazoBilled": { "compute": {...}, "model": {...}, "storage": {...}, "primitives": {...}, "total": {...} },
#   "providerDirect": { "compute": {...}, "model": {...}, "total": {...} }
# }
GET/v1/usage/daily

Daily cost time series. Returns a bare array (not wrapped in { data: ... }).

Parameters

periodstringSee period values above. Default: last_30_days.

Response

DailyUsage[]

Example

bash
curl "https://api.theazo.com/v1/usage/daily?period=last_30_days" \
  -H "Authorization: Bearer th_live_..."

# Response (bare array, no wrapper):
# [
#   { "date": "2025-05-01", "cost": { "amount": 580, "currency": "usd" }, "computeMinutes": 12, "modelCalls": 48, "tokens": 91000 },
#   { "date": "2025-05-02", "cost": { "amount": 720, "currency": "usd" }, "computeMinutes": 15, "modelCalls": 61, "tokens": 118500 }
# ]
GET/v1/usage/users/:userId

Usage for a single user (not a top-N listing — there's no bare GET /v1/usage/users). To build a per-user leaderboard, aggregate client-side or use the export endpoint below.

Parameters

periodstringSee period values above. Default: month.

Response

UserUsage

Example

bash
curl "https://api.theazo.com/v1/usage/users/user_123?period=month" \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "compute": { "minutes": 42, "cost": { "amount": 84, "currency": "usd" } },
#   "models": { "calls": 120, "tokens": { "input": 98000, "output": 31000 }, "cost": { "amount": 210, "currency": "usd" } },
#   "storage": { "gbHours": 2.1, "cost": { "amount": 4, "currency": "usd" } },
#   "total": { "amount": 298, "currency": "usd" },
#   "breakdown": [ { "date": "2025-05-01", "total": { "amount": 58, "currency": "usd" } } ]
# }
GET/v1/usage/models

Per-model cost breakdown for the platform.

Parameters

periodstringSee period values above. Default: month.

Response

{ data: ModelUsage[] }

Example

bash
curl "https://api.theazo.com/v1/usage/models?period=month" \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "data": [
#     { "model": "anthropic/claude-sonnet", "calls": 1200, "tokens": { "input": 980000, "output": 310000 }, "cost": { "amount": 2100, "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, based on the workflow's completed run history (min/max of past run costs). If there are no completed runs yet, falls back to a rough per-step heuristic with 'low' confidence.

Response

WorkflowEstimate

Example

bash
curl -X POST https://api.theazo.com/v1/workflows/wf_01HX.../estimate \
  -H "Authorization: Bearer th_live_..."

# Response:
# {
#   "estimated": { "min": 40, "max": 210, "currency": "usd" },
#   "confidence": "medium",
#   "breakdown": [],
#   "basedOn": 14
# }
#
# "basedOn" is the number of completed runs the estimate is derived from.
# "confidence" is "low" (<10 runs, or no runs — a rough stepCount*5..stepCount*50
# heuristic), "medium" (10-99 runs), or "high" (100+ runs).
GET/v1/workflow-runs/:runId/stream

SSE stream of workflow execution events, published as the engine progresses through the run.

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 names match the "event" field in each frame's data):
# event: connected
# data: {"runId":"wfr_...","status":"running"}
#
# event: started
# data: {"event":"started","runId":"wfr_..."}
#
# event: step.completed
# data: {"event":"step.completed","runId":"wfr_...","stepId":"scrape","cost":{"amount":2,"currency":"usd"}}
#
# event: step.failed
# data: {"event":"step.failed","runId":"wfr_...","stepId":"scrape","error":"..."}
#
# event: run.completed
# data: {"event":"run.completed","runId":"wfr_...","totalCost":{"amount":95,"currency":"usd"}}
#
# A "heartbeat" event is sent every 15s to keep the connection alive. If the run is
# already terminal (completed/failed/partial/cancelled) when you connect, you get a
# single "run.<status>" event and the stream ends immediately.

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 items within the fleet complete, and when the fleet itself starts, completes, or is cost-paused.

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: fleet.started
# data: {"event":"fleet.started"}
#
# event: item.completed
# data: {"event":"item.completed","itemId":"itm_...","cost":{"amount":8,"currency":"usd"}}
#
# event: fleet.paused
# data: {"event":"fleet.paused","reason":"cost_limit"}
#
# event: fleet.completed
# data: {"event":"fleet.completed","totalCost":{"amount":82,"currency":"usd"}}
#
# There is no per-agent "start" event — only completions are published as items finish.

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. The schedule runs the given agent definition on the cron; pass input to hand each run a payload.

Parameters

agentstringAgent definition name or ID the schedule runs.
userIdstringrequiredUser the scheduled runs are attributed to.
namestring
cronstringrequiredCron expression (5 fields: minute hour day-of-month month day-of-week).
timezonestringIANA timezone for cron evaluation. Default: UTC.
inputRecord<string, unknown>Input passed to each scheduled agent run.

Response

Schedule

Example

bash
curl -X POST https://api.theazo.com/v1/schedules \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "daily-report-generator",
    "userId": "user_123",
    "cron": "0 9 * * 1-5",
    "input": { "report": "daily-metrics" }
  }'
GET/v1/schedules

List all schedules for the platform (no status filter — fetch all and filter client-side if needed).

Response

{ data: Schedule[] }

Example

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

Get a single schedule.

Response

Schedule

Example

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

Update a schedule (all fields optional; same shape as create). Omitted fields keep their stored value.

Parameters

agentstringAgent definition name or ID the schedule runs.
userIdstringrequiredUser the scheduled runs are attributed to.
namestring
cronstringrequiredCron expression (5 fields: minute hour day-of-month month day-of-week).
timezonestringIANA timezone for cron evaluation. Default: UTC.
inputRecord<string, unknown>Input passed to each scheduled agent run.

Response

Schedule

Example

bash
curl -X PUT 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

{ ok: true }

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

{ ok: true }

Example

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

Execution history for a schedule.

Response

{ data: ScheduleExecution[] }

Example

bash
curl https://api.theazo.com/v1/schedules/sched_01HX.../history \
  -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 (type defaults to 'webhook'). Returns a unique trigger URL and secret (the secret is shown once, on create — reads redact it). For event triggers (type: 'event') see the Scheduling & Triggers guide.

Parameters

agentstringAgent definition name or ID the trigger runs.
userIdstringrequiredUser the triggered runs are attributed to.
namestringHuman-readable trigger name.
type'webhook'requiredCreates a signed webhook URL that fires the agent when POSTed to.

Response

Trigger

Example

bash
curl -X POST https://api.theazo.com/v1/triggers \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "agent": "code-reviewer",
    "name": "GitHub push handler"
  }'

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

List all triggers (secrets redacted).

Response

{ data: Trigger[] }

Example

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

Get one trigger (secret redacted).

Response

Trigger

Example

bash
curl https://api.theazo.com/v1/triggers/trg_01HX... \
  -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/triggers/:id/fire

Fire a trigger. Note the path — NOT under /v1. This is the public webhook receiver, no Bearer auth. Requests must include a valid HMAC-SHA256 signature (of the raw body, using the trigger's secret) in the x-trigger-signature header. The request body is passed as input to the action; firing enqueues a job and returns immediately — it does not wait for the run to finish.

Response

{ ok: true, jobId: string }

Example

bash
curl -X POST https://api.theazo.com/triggers/trg_01HX.../fire \
  -H "Content-Type: application/json" \
  -H "x-trigger-signature: ..." \
  -d '{ "ref": "refs/heads/main", "commits": [...] }'

# Response:
# { "ok": true, "jobId": "job_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 channel. The body is discriminated on `type` ('chat_embed' | 'slack' | 'email' | 'phone') — each type has its own config fields (chat_embed: theme; slack: workspace/channels/botName; email: address; phone: phoneNumber/voice). Returns a scriptTag for chat_embed channels.

Parameters

typestringrequired'chat_embed' | 'slack' | 'email' | 'phone'.
agentstringrequiredAgent definition ID to back this channel.

Response

Channel

Example

bash
curl -X POST https://api.theazo.com/v1/channels \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "chat_embed",
    "agent": "adef_...",
    "theme": "dark"
  }'

# Response includes a scriptTag for chat_embed channels:
# { "id": "ch_01HX...", "scriptTag": "<script src=\"https://widget.theazo.com/w/ch_01HX....js\"></script>", ... }
GET/v1/channels

List all channels.

Response

{ data: Channel[] }

Example

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

The 3 endpoints below back the embeddable chat widget. They're mounted at /channels/... — not under /v1 — and take no Bearer auth (the channel ID is effectively the access token; rate-limited per channel, visitor, and IP instead).

POST/channels/:channelId/messages

Send a message as a visitor and get the agent's reply (synchronous — waits for the full response). Finds or creates a conversation for the given visitorId.

Parameters

textstringrequiredThe visitor's message text.
visitorIdstringrequiredStable per-visitor identifier (e.g. a client-generated UUID persisted in localStorage).

Response

{ messageId, conversationId, response: { role, content } }

Example

bash
curl -X POST https://api.theazo.com/channels/ch_01HX.../messages \
  -H "Content-Type: application/json" \
  -d '{ "text": "How do I reset my password?", "visitorId": "visitor_abc123" }'
GET/channels/:channelId/messages

Get message history for a visitor's conversation on this channel.

Parameters

visitorIdstringrequiredRequired — identifies which visitor's conversation to fetch.
limitnumberMax messages to return. Default: 50.

Response

{ conversationId: string | null, messages: { id, role, content, createdAt }[] }

Example

bash
curl "https://api.theazo.com/channels/ch_01HX.../messages?visitorId=visitor_abc123&limit=20"
GET/channels/:channelId/stream

SSE stream for a visitor's conversation on this channel. Emits 'connected' on open, 'message' events as messages are sent/received, and a 'heartbeat' every 15s. Connection closes automatically after 10 minutes.

Parameters

visitorIdstringrequiredRequired — same visitorId used for the messages endpoints.

Response

text/event-stream

Example

bash
curl -N "https://api.theazo.com/channels/ch_01HX.../stream?visitorId=visitor_abc123"

# Stream output:
# event: connected
# data: {"channelId":"ch_01HX...","visitorId":"visitor_abc123"}
#
# event: message
# data: {"event":"message","role":"assistant","content":"To reset your password...","messageId":"msg_..."}
#
# event: heartbeat
# data: {"t":1735689600000}

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.
Pro300 req / minProduction workloads.
EnterpriseCustomDedicated limits negotiated per contract.
PreviousWebhooksNextErrors
Was this page helpful?