Public API

Use it when you want an agent behind a backend job, a webhook, a support tool or any language that can make an HTTP request. It is the simplest way to put a Studio agent into production outside the Studio UI.

Base URL

https://{STUDIO_HOST}/api/v1/agents/{agentId}/runs

The same routes are also served under the app base path (https://{STUDIO_HOST}/studio/api/v1/agents/{agentId}/runs), which is the URL shown in Settings → API keys. Both behave identically.

Authentication

Send your key as a bearer token:

Authorization: Bearer studio_xxxxxxxxxxxxxxxx

The routes

All paths are relative to /api/v1/agents/{agentId}.

Start a run

curl -X POST "https://$STUDIO_HOST/api/v1/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $STUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 01928f3e-7b6a-7c1d-9a2b-3c4d5e6f7a8b" \
  -d '{ "input": "Summarise the Q3 revenue report.", "mode": "sync" }'

Body

Unknown fields are rejected. The body is capped at 4 MB.

The three modes

Response headers

The run object

{
  "id": "0192…",
  "agentId": "0192…",
  "sessionId": "0192…",
  "status": "succeeded",
  "output": "Q3 revenue grew 12%…",
  "error": null,
  "usage": { "inputTokens": 1840, "outputTokens": 312, "costUsd": 0.0041 },
  "pendingInputs": [],
  "createdAt": "2026-10-26T09:12:03.000Z",
  "completedAt": "2026-10-26T09:12:09.000Z"
}

Streaming

Both mode: "stream" and GET /runs/{runId}/events return Server-Sent Events. Every frame carries an id (its index), an event name and JSON data.

A : heartbeat comment is sent every 15 seconds so proxies keep the connection open.

Answer a question

When a run is awaiting_input:

curl -X POST "https://$STUDIO_HOST/api/v1/agents/$AGENT_ID/runs/$RUN_ID/respond" \
  -H "Authorization: Bearer $STUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "req_123", "response": { "optionId": "approve" } }'

response is either a plain string, or an object with optionId and/or text (at least one). The run continues and the call returns the updated run.

Cancel a run

curl -X POST "https://$STUDIO_HOST/api/v1/agents/$AGENT_ID/runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $STUDIO_API_KEY"

Idempotency

Send an Idempotency-Key header (a UUID v7) when starting a run.

• Same key, same body → you get the same run back. A network retry is always safe.
• Same key, different body → 409 conflict.
• No key → Studio generates one, so every request starts a new run.

Rate limits

• Starting a run is limited per key, by default 60 requests per minute (fixed one-minute window). Your deployment may set a different value; it is shown in Settings → API keys.
• Over the limit you get 429 rate_limit_exceeded with a Retry-After header.
• Reading, streaming, responding and cancelling are not rate limited.

Errors

Errors use RFC 7807 application/problem+json:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request body failed validation",
  "code": "validation_error",
  "requestId": "req_0192…",
  "errors": [{ "field": "input", "message": "Required" }]
}

What the Public API does not do

• It does not list agents or sessions. Use the MCP server or the Studio APIs for that.
• It does not create or edit agents. Build them in Studio, publish, then call them here.

Production checklist

• The key lives in a backend secret manager, never in a browser or mobile app
• Every run start sends an Idempotency-Key, and retries reuse it
• awaiting_input is handled, or human-in-the-loop agents will look stuck
• failed with guardrail_blocked is shown as a policy message, not a crash
• 429 backs off using Retry-After
• Streams reconnect with Last-Event-ID
• X-Request-Id is logged on your side