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:class="cb-cmt">//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:class="cb-cmt">//api.theazo.com/v1/sessions \
  -H class="cb-str">"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
{
  class="cb-str">"error": {
    class="cb-str">"code": class="cb-str">"rate_limited",
    class="cb-str">"message": class="cb-str">"Too many requests. Retry after 2 seconds.",
    class="cb-str">"details": { class="cb-str">"retryAfter": class="cb-num">2 },
    class="cb-str">"requestId": class="cb-str">"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:class="cb-cmt">//api.theazo.com/v1/sessions \
  -H class="cb-str">"Authorization: Bearer th_live_..." \
  -H class="cb-str">"Content-Type: application/json" \
  -d '{
    class="cb-str">"userId": class="cb-str">"user_123",
    class="cb-str">"limits": {
      class="cb-str">"maxCost": { class="cb-str">"amount": class="cb-num">500, class="cb-str">"currency": class="cb-str">"usd", class="cb-str">"period": class="cb-str">"day" },
      class="cb-str">"maxAgents": class="cb-num">3
    },
    class="cb-str">"metadata": { class="cb-str">"plan": class="cb-str">"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:class="cb-cmt">//api.theazo.com/v1/sessions/by-user/user_123 \
  -H class="cb-str">"Authorization: Bearer th_live_..." \
  -H class="cb-str">"Content-Type: application/json" \
  -d '{
    class="cb-str">"limits": {
      class="cb-str">"maxCost": { class="cb-str">"amount": class="cb-num">1000, class="cb-str">"currency": class="cb-str">"usd", class="cb-str">"period": class="cb-str">"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:class="cb-cmt">//api.theazo.com/v1/sessions/ses_01HX.../agents \
  -H class="cb-str">"Authorization: Bearer th_live_..." \
  -H class="cb-str">"Content-Type: application/json" \
  -d '{
    class="cb-str">"browser": true,
    class="cb-str">"tools": [class="cb-str">"web_search", class="cb-str">"write_file"],
    class="cb-str">"instructions": class="cb-str">"You are a research assistant. Be concise.",
    class="cb-str">"timeout": class="cb-num">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:class="cb-cmt">//api.theazo.com/v1/agents/agt_01HX.../run \
  -H class="cb-str">"Authorization: Bearer th_live_..." \
  -H class="cb-str">"Content-Type: application/json" \
  -d class="cb-str">'{ "task": "Summarize the top 5 AI research papers from this week" }'

# Response:
# { class="cb-str">"taskId": class="cb-str">"task_01HX...", class="cb-str">"agentId": class="cb-str">"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:class="cb-cmt">//api.theazo.com/v1/agents/agt_01HX.../exec \
  -H class="cb-str">"Authorization: Bearer th_live_..." \
  -H class="cb-str">"Content-Type: application/json" \
  -d '{
    class="cb-str">"lang": class="cb-str">"python",
    class="cb-str">"code": class="cb-str">"print(2 + 2)"
  }'

# Response:
# { class="cb-str">"stdout": class="cb-str">"4\n", class="cb-str">"stderr": class="cb-str">"", class="cb-str">"exitCode": class="cb-num">0, class="cb-str">"durationMs": class="cb-num">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:class="cb-cmt">//api.theazo.com/v1/agents/agt_01HX.../stream \
  -H class="cb-str">"Authorization: Bearer th_live_..." \
  -H class="cb-str">"Accept: text/event-stream"

# Stream output:
# event: thinking
# data: {class="cb-str">"text":class="cb-str">"I'll search for recent AI papers..."}
#
# event: tool_call
# data: {class="cb-str">"tool":class="cb-str">"web_search",class="cb-str">"input":{class="cb-str">"query":class="cb-str">"AI papers 2025"}}
#
# event: output
# data: {class="cb-str">"text":class="cb-str">"Here are the top 5...",class="cb-str">"cost":{class="cb-str">"amount":class="cb-num">12,class="cb-str">"currency":class="cb-str">"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:class="cb-cmt">//api.theazo.com/v1/agents/agt_01HX.../pause \
  -H class="cb-str">"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:class="cb-cmt">//api.theazo.com/v1/agents/agt_01HX.../resume \
  -H class="cb-str">"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:class="cb-cmt">//api.theazo.com/v1/agents/agt_01HX.../terminate \
  -H class="cb-str">"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 class="cb-str">"https://api.theazo.com/v1/usage/summary?from=2025-05-01"mary?from=2025-05-01" \
  -H class="cb-str">"Authorization: Bearer th_live_..."

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

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=class="cb-num">25

// Response
{
  class="cb-str">"data": [...],
  class="cb-str">"nextCursor": class="cb-str">"cur_01HX3K...",
  class="cb-str">"hasMore": true
}

// Next page
GET /v1/sessions?limit=class="cb-num">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.
PreviousWebhooksNextBYOI
Was this page helpful?
Ask anything...⌘I