{"openapi":"3.1.0","info":{"title":"camelRun API","version":"1.0.0"},"security":[{"bearer":[]},{"console":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Operator or API token"},"browser":{"type":"http","scheme":"bearer","description":"A browser token (POST /v1/agents/{id}/browser-tokens): reads one agent's events, state, history and inputs, until it expires"},"console":{"type":"apiKey","in":"cookie","name":"ar_session","description":"Console session; mutations also need X-Agent-Runtime-Console: 1"}},"schemas":{"Event_run_started":{"type":"object","properties":{"id":{"type":"string","description":"evt_…: the same each time the event is sent; dedupe by it","example":"evt_3f9c0a1b2c3d4e5f60718293"},"type":{"type":"string","enum":["run.started"]},"created":{"type":"number","description":"When it happened, in Unix seconds"},"data":{"type":"object","properties":{"agentId":{"type":"string"},"requestId":{"type":"string"},"method":{"type":"string","enum":["prompt","continue","resume","execute"]},"actor":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"The metadata the message that started it carried"},"resumes":{"type":"number","description":"Set when a node resumed a turn whose node was lost"}},"required":["agentId","requestId","method"]}},"required":["id","type","created","data"],"description":"A run began"},"Event_run_completed":{"type":"object","properties":{"id":{"type":"string","description":"evt_…: the same each time the event is sent; dedupe by it","example":"evt_3f9c0a1b2c3d4e5f60718293"},"type":{"type":"string","enum":["run.completed"]},"created":{"type":"number","description":"When it happened, in Unix seconds"},"data":{"type":"object","properties":{"agentId":{"type":"string"},"requestId":{"type":"string"},"method":{"type":"string","enum":["prompt","continue","resume","execute"]},"actor":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"The metadata the message that started it carried"},"usage":{"type":["object","null"],"properties":{"responses":{"type":"number"},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"costUsd":{"type":"number"}},"required":["responses","input","output","cacheRead","cacheWrite","costUsd"],"description":"The run's model responses on the node that ended it; null when it made none there"},"servedModel":{"type":"string","description":"The model that made the run's last response, as provider/model-id"},"stopped":{"type":"string","enum":["input_required","spend_limit","turn_limit"],"description":"Why it stopped early: waiting on input (inputIds), a spend limit, or the run's own limits (turn_limit: its model responses or time, see runLimits)"},"limit":{"type":"string","enum":["run","agent","tenant","credit"],"description":"With stopped spend_limit, which limit stopped it: the run's own (spendLimit on the prompt), its agent's, the tenant's monthly cap, or the account's prepaid credit"},"inputIds":{"type":"array","items":{"type":"string"}},"replyIndex":{"type":"number","description":"The final assistant message's index in the agent's history"},"messageCount":{"type":"number","description":"Messages in the agent's history after it"},"steeredInto":{"type":"string","description":"A prompt sent with whileRunning: steer that a running turn took: that turn's request"}},"required":["agentId","requestId","method","usage"]}},"required":["id","type","created","data"],"description":"A run ended without an error"},"Event_run_failed":{"type":"object","properties":{"id":{"type":"string","description":"evt_…: the same each time the event is sent; dedupe by it","example":"evt_3f9c0a1b2c3d4e5f60718293"},"type":{"type":"string","enum":["run.failed"]},"created":{"type":"number","description":"When it happened, in Unix seconds"},"data":{"type":"object","properties":{"agentId":{"type":"string"},"requestId":{"type":"string"},"method":{"type":"string","enum":["prompt","continue","resume","execute"]},"actor":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"The metadata the message that started it carried"},"usage":{"type":["object","null"],"properties":{"responses":{"type":"number"},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"costUsd":{"type":"number"}},"required":["responses","input","output","cacheRead","cacheWrite","costUsd"],"description":"The run's model responses on the node that ended it; null when it made none there"},"servedModel":{"type":"string","description":"The model that made the run's last response, as provider/model-id"},"error":{"type":"string"},"code":{"type":"string","description":"The failure's name, where it has one: cancelled (a stop cancelled it before it began), aborted, model_stream_stalled, turn_limit, spend_limit, output_missing..."},"uncertain":{"type":"boolean","description":"A restart cut it short: its effects are unknown"},"steeredInto":{"type":"string"},"errorClass":{"type":"string","enum":["billing","rate_limit","server","refusal","auth","timeout","other"],"description":"What kind of failure: billing (the provider's 402, a quota or budget used up), rate_limit (429), server (5xx, overloaded, the provider unreachable), refusal (the model declined, or a safety filter stopped it), auth (401, 403, no key), timeout (the provider's, or the model stream went quiet), other. Values may be added: treat an unknown one as other"},"providerStatus":{"type":"integer","description":"The provider's HTTP status, when its error gives one"},"retryable":{"type":"boolean","description":"Whether the runtime retries such a failure itself (3 times, with backoff, on the same model). On a failed run: true means it was transient and its retries ran out, so trying again later, or another model, may work"},"model":{"type":"string","description":"The model that failed, as provider/model-id (an id of GET /v1/models)"}},"required":["agentId","requestId","method","usage","error"]}},"required":["id","type","created","data"],"description":"A run ended with an error: the runtime's, or the model's"},"Event_input_requested":{"type":"object","properties":{"id":{"type":"string","description":"evt_…: the same each time the event is sent; dedupe by it","example":"evt_3f9c0a1b2c3d4e5f60718293"},"type":{"type":"string","enum":["input.requested"]},"created":{"type":"number","description":"When it happened, in Unix seconds"},"data":{"type":"object","properties":{"agentId":{"type":"string"},"requestId":{"type":"string"},"inputId":{"type":"string"},"toolCallId":{"type":"string"},"kind":{"type":"string","enum":["question","approval","form","url"]},"expiresAt":{"type":"number"}},"required":["agentId","requestId","inputId","toolCallId","kind","expiresAt"]}},"required":["id","type","created","data"],"description":"The agent asks a person for input; the run waits"},"Event_input_resolved":{"type":"object","properties":{"id":{"type":"string","description":"evt_…: the same each time the event is sent; dedupe by it","example":"evt_3f9c0a1b2c3d4e5f60718293"},"type":{"type":"string","enum":["input.resolved"]},"created":{"type":"number","description":"When it happened, in Unix seconds"},"data":{"type":"object","properties":{"agentId":{"type":"string"},"requestId":{"type":"string"},"inputId":{"type":"string"},"state":{"type":"string","enum":["answered","declined","cancelled","expired","superseded"]}},"required":["agentId","requestId","inputId","state"]}},"required":["id","type","created","data"],"description":"An input settled"},"Event_usage_recorded":{"type":"object","properties":{"id":{"type":"string","description":"evt_…: the same each time the event is sent; dedupe by it","example":"evt_3f9c0a1b2c3d4e5f60718293"},"type":{"type":"string","enum":["usage.recorded"]},"created":{"type":"number","description":"When it happened, in Unix seconds"},"data":{"type":"object","properties":{"agentId":{"type":["string","null"],"description":"null for a transcription made with POST /v1/transcriptions, or images made with POST /v1/images, which no agent made"},"requestId":{"type":["string","null"]},"subject":{"type":["string","null"]},"actor":{"type":["string","null"]},"context":{"type":"object","additionalProperties":{}},"keyScope":{"type":["string","null"]},"provider":{"type":"string"},"model":{"type":"string"},"kind":{"type":"string","enum":["response","compaction","transcription","image"],"description":"response: a model response of a run; compaction: a summary of older context; transcription: audio transcribed (audioSeconds of it; no tokens); image: images made (images of them; input is text and image tokens in, output image tokens out)"},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"reasoning":{"type":"number"},"audioSeconds":{"type":"number","description":"For a transcription: the seconds of audio billed"},"images":{"type":"number","description":"For images made: how many"},"cost":{"type":"object","properties":{"usd":{"type":"number"},"source":{"type":"string","enum":["provider","catalog"]}},"required":["usd","source"]},"at":{"type":"number"}},"required":["agentId","requestId","subject","actor","context","keyScope","provider","model","kind","input","output","cacheRead","cacheWrite","cost","at"]}},"required":["id","type","created","data"],"description":"A model response's usage and cost, a transcription's, or images'"},"Error":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong, for people"},"code":{"type":"string","description":"What went wrong, for code: INVALID_REQUEST (400: the request is malformed or invalid); UNAUTHORIZED (401: no valid token); PAYMENT_REQUIRED (402); FORBIDDEN (403: the token may not do this); NOT_FOUND (404); CONFLICT (409); GONE (410); TOO_LARGE (413); RATE_LIMITED (429: retry after Retry-After); UNAVAILABLE (503: retry after Retry-After); DATABASE_RETRY (503: the database refused the request for now (a conflict with another, or a statement timeout); retry after Retry-After); INTERNAL (500); BUSY_AGENT_LIMIT (429: the tenant has as many agents busy as it may (the body's busyAgents, a BusyAgents, says the limit, its usage tier and the next); retry after Retry-After); SPEND_LIMIT (402: a spend limit (the agent's, or the tenant's monthly cap) is reached); INSUFFICIENT_CREDIT (402: the tenant's prepaid credit is spent); STORAGE_LIMIT (507: the tenant's storage limit would be passed; the body has limit and used, in bytes); IDEMPOTENCY_CONFLICT (409: the Idempotency-Key or request id was used for another request); IDEMPOTENCY_IN_PROGRESS (409: the first request with this Idempotency-Key is still running; retry); APPLICATION_CONNECTED (409: another connection serves this agent's tools; connect with ?takeover=true to replace it); APPLICATION_NOT_CONNECTED (409: this agent's tools need its application, and none is connected; connect it, or send allowDisconnected: true); REPLAY_GAP (409: the Last-Event-ID is behind the buffer; read state (or ask for a snapshot) and continue from its cursor); AGENT_KEYLESS (409: the agent was made without a key, so its credentials cannot be given again (GET /v1/agents/{id}/credentials)). Others may be added"},"limit":{"type":"object","properties":{"name":{"type":"string","description":"api_requests, auth_requests, signups, agent_creates or runs"},"scope":{"type":"string","enum":["ip","tenant"]},"max":{"type":"integer"},"windowSeconds":{"type":"integer"}},"required":["name","scope","max","windowSeconds"],"description":"On a rate limit's 429: the limit reached. Retry-After says when to retry"}},"required":["error","code"]},"VolumeFile":{"type":"object","properties":{"path":{"type":"string"},"version":{"type":"number"},"size":{"type":"number"},"updatedAt":{"type":"number"},"by":{"type":"string"},"contentType":{"type":"string","description":"As uploaded (Content-Type), else sniffed from the file's first bytes and name"}},"required":["path","version","size","updatedAt","contentType"]},"FileManifest":{"type":"object","properties":{"snapshot":{"type":"string","description":"The snapshot made for the call, which every URL here reads"},"root":{"type":"string","description":"The directory, as the agent names it"},"files":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/FileValue"},{"type":"object","properties":{"path":{"type":"string","description":"Relative to root"}},"required":["path"]}],"description":"A file sent to a tool, as MCP SEP-2631 (draft) describes one"}},"archive":{"type":"object","properties":{"uri":{"type":"string"},"mimeType":{"type":"string","enum":["application/gzip"]}},"required":["uri","mimeType"],"description":"Every file, as a tar.gz with paths relative to root"}},"required":["snapshot","root","files","archive"],"description":"A directory sent to a tool: its files as they were when the call was made"},"FileValue":{"type":"object","properties":{"uri":{"type":"string","description":"A URL to the file, bound to the call (GET /v1/files/{token}/{name}), or a data: URI"},"name":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"number"},"digest":{"type":"object","properties":{"algorithm":{"type":"string","enum":["sha-256"]},"value":{"type":"string","description":"Hex"}},"required":["algorithm","value"],"description":"Absent for files over 64 MiB"}},"required":["uri","name","mimeType","size"],"description":"A file sent to a tool, as MCP SEP-2631 (draft) describes one"},"Me":{"type":"object","properties":{"tenant":{"type":"string"},"via":{"type":"string","enum":["operator","token","console","oauth"]},"login":{"type":"string","description":"Who the tenant belongs to: the Google or sign-in address, or the GitHub login, it signed in with"},"name":{"type":"string","description":"The person's display name, for console sessions signed in with Google or GitHub"},"signIn":{"type":"string","enum":["github","google","password"],"description":"How a console session was signed in"},"canStoreKeys":{"type":"boolean"},"defaultModel":{"type":"string","description":"The model an agent of this tenant gets when it names none, as provider/model-id: the first of the runtime's defaults (Claude Sonnet 5.5 on Anthropic, OpenRouter, then Bedrock, ...) the tenant has a key for. An agent with a key scope counts the scope's keys too","example":"anthropic/claude-sonnet-5-5"}},"required":["tenant","via","canStoreKeys","defaultModel"]},"Provider":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["model","search","fetch"],"description":"model: an LLM provider; search: a web search API, whose key the web_search built-in uses; fetch: a page renderer web_fetch uses for JavaScript-only pages"},"models":{"type":"integer"},"apiKey":{"type":"boolean","description":"Whether one API key is enough to use this provider"},"requires":{"type":"string","description":"What the provider needs instead of an API key"},"key":{"$ref":"#/components/schemas/KeyStatus"},"custom":{"type":"object","properties":{"type":{"type":"string","enum":["openai-completions","openai-responses","anthropic-messages"]},"baseUrl":{"type":"string"},"auth":{"type":"string","enum":["x-api-key","bearer"],"description":"How the key is sent"},"headers":{"type":"array","items":{"type":"string"},"description":"The names of its headers, never their values"},"models":{"type":"array","items":{"$ref":"#/components/schemas/CustomModel"}}},"required":["type","baseUrl","auth","models"],"description":"A provider of the tenant's own (PUT /v1/providers/{name}) or of a key scope (PUT /v1/key-scopes/{scope}/model-providers/{name}): its API, where it is, and the models it declares"}},"required":["id","kind","models","apiKey","key"]},"KeyStatus":{"type":["object","null"],"properties":{"provider":{"type":"string"},"source":{"type":"string","enum":["tenant","admin","platform"],"description":"tenant: set by the tenant; admin: set by the runtime operator; platform: the platform's key, which a prepaid tenant pays for from credit (an admin tenant uses it unbilled, unless its entry sets platformKeys: false)"},"last4":{"type":"string"},"setAt":{"type":"number"},"region":{"type":"string","description":"For the tenant's own amazon-bedrock key: the AWS region its calls go to"}},"required":["provider","source"]},"CustomModel":{"type":"object","properties":{"id":{"type":"string","description":"The model's id on the server; agents name it <provider>/<id>","example":"llama-4-scout"},"contextWindow":{"type":"integer","description":"Its context window in tokens: compaction keeps each request within it"},"maxOutputTokens":{"type":"integer","description":"The most it writes in a reply; default 8,192, or half a smaller context window"},"input":{"type":"array","items":{"type":"string","enum":["text","image"]},"description":"[\"text\", \"image\"] for a model that sees images; default [\"text\"]"},"reasoning":{"type":"boolean","description":"Whether it reasons (thinkingLevel applies)"},"pricing":{"type":"object","properties":{"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"}},"required":["input","output"],"description":"USD per million tokens, for usage, spend limits and webhooks; none: free"},"compat":{"type":"object","properties":{"supportsDeveloperRole":{"type":"boolean"},"supportsUsageInStreaming":{"type":"boolean"},"supportsFinishReason":{"type":"boolean"},"supportsReasoningEffort":{"type":"boolean"},"maxTokensField":{"type":"string","enum":["max_tokens","max_completion_tokens"]},"thinkingFormat":{"type":"string","enum":["openai","openrouter","deepseek","together","zai","qwen","qwen-chat-template"]}},"description":"Switches for a server that differs from OpenAI's: a developer role, usage in the stream (default true), reasoning_effort, the max tokens field, how thinking is asked for"}},"required":["id","contextWindow"]},"CustomProviderInput":{"type":"object","properties":{"type":{"type":"string","enum":["openai-completions","openai-responses","anthropic-messages"],"description":"The API the server speaks: openai-completions, OpenAI Chat Completions (POST <baseUrl>/chat/completions); openai-responses, OpenAI Responses (POST <baseUrl>/responses); anthropic-messages, Anthropic Messages (POST <baseUrl>/v1/messages)"},"baseUrl":{"type":"string","description":"Its API root, public and https (the outbound guard checks it when saved and at every call): with /v1 for the OpenAI APIs, without for Anthropic's","example":"https://api.example.com/v1"},"apiKey":{"type":["string","null"],"description":"Sent as Authorization: Bearer (x-api-key for Anthropic Messages); left out keeps the stored key, null removes it (a server that takes none)"},"headers":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Headers for each call, sealed like the key; left out keeps the stored ones, null removes them"},"auth":{"type":"string","enum":["x-api-key","bearer"],"description":"anthropic-messages only: \"bearer\" sends the key as Authorization: Bearer, as some gateways and proxies take it, instead of x-api-key (the default). Saved again without it, x-api-key"},"models":{"type":"array","items":{"$ref":"#/components/schemas/CustomModel"},"minItems":1,"maxItems":200}},"required":["type","baseUrl","models"]},"KeySet":{"type":"object","properties":{"provider":{"type":"string"},"last4":{"type":"string"},"region":{"type":"string"},"verification":{"type":"object","properties":{"status":{"type":"string","enum":["valid","unverified","invalid"]},"detail":{"type":"string"}},"required":["status"]}},"required":["provider","last4","verification"]},"KeyInput":{"type":"object","properties":{"apiKey":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^\\S+$"},"verify":{"type":"boolean","description":"false stores the key without checking it with the provider"},"region":{"type":"string","description":"amazon-bedrock only, and required for it: the AWS region its calls go to (the key is a Bedrock API key, sent as a bearer token)","example":"us-west-2"}},"required":["apiKey"]},"KeyScope":{"type":"object","properties":{"scope":{"type":"string"},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"last4":{"type":"string","description":"Absent for an entry without a key"},"baseUrl":{"type":"string"},"region":{"type":"string"},"headers":{"type":"array","items":{"type":"string"},"description":"The extra headers' names; never their values"},"setAt":{"type":"number"}},"required":["provider","setAt"]}}},"required":["scope","providers"]},"KeyScopeEntryInput":{"type":"object","properties":{"apiKey":{"type":"string","minLength":1,"maxLength":4096,"description":"The provider's API key (for amazon-bedrock, a Bedrock API key, sent as a bearer token). Leave it out for a gateway at baseUrl that holds the key: no auth header is sent, only headers"},"baseUrl":{"type":"string","description":"An HTTPS endpoint that replaces the provider's API root in each request: https://openrouter.ai/api/v1, https://api.anthropic.com or https://api.openai.com/v1 (an AI gateway's /openrouter, /anthropic or /openai); for other providers, the model's base URL","example":"https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/openrouter"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Extra headers for every call, sealed like the key, e.g. cf-aig-authorization"},"region":{"type":"string","description":"amazon-bedrock only: the AWS region to call; read from baseUrl https://bedrock-runtime.<region>.amazonaws.com when left out","example":"us-west-2"}},"additionalProperties":false},"WebhookEndpointCreated":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string","description":"The Standard Webhooks signing secret (whsec_…); shown only this once"}},"required":["secret"]}]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["run.started","run.completed","run.failed","input.requested","input.resolved","usage.recorded","billing.balance.low","billing.balance.depleted","billing.topup.receipt","billing.topup.declined","billing.topup.action_required","billing.topup.no_card","billing.topup.limit","billing.topup.reconcile"]},"description":"The event types it receives: run.started, run.completed, run.failed, input.requested, input.resolved, usage.recorded"},"description":{"type":"string"},"createdAt":{"type":"number"},"setBy":{"type":["string","null"],"description":"Who last set where it sends: \"token:<API token id>\", \"oauth:<grant id>\", \"console\" or \"operator\"; null if set before this was recorded. Revoking that token lists it"}},"required":["id","url","events","createdAt","setBy"]},"WebhookEndpointInput":{"type":"object","properties":{"url":{"type":"string","description":"An HTTPS URL that receives the events, each a POST signed per Standard Webhooks","example":"https://example.com/hooks/agents"},"events":{"type":"array","items":{"type":"string","enum":["run.started","run.completed","run.failed","input.requested","input.resolved","usage.recorded","billing.balance.low","billing.balance.depleted","billing.topup.receipt","billing.topup.declined","billing.topup.action_required","billing.topup.no_card","billing.topup.limit","billing.topup.reconcile"]},"description":"The event types it receives: run.started, run.completed, run.failed, input.requested, input.resolved, usage.recorded"},"description":{"type":"string","maxLength":500}},"required":["url","events"],"additionalProperties":false},"WebhookEndpointUpdate":{"type":"object","properties":{"url":{"type":"string","description":"An HTTPS URL that receives the events, each a POST signed per Standard Webhooks","example":"https://example.com/hooks/agents"},"events":{"type":"array","items":{"type":"string","enum":["run.started","run.completed","run.failed","input.requested","input.resolved","usage.recorded","billing.balance.low","billing.balance.depleted","billing.topup.receipt","billing.topup.declined","billing.topup.action_required","billing.topup.no_card","billing.topup.limit","billing.topup.reconcile"]},"description":"The event types it receives: run.started, run.completed, run.failed, input.requested, input.resolved, usage.recorded"},"description":{"type":"string","maxLength":500}},"additionalProperties":false},"WebhookSecret":{"type":"object","properties":{"secret":{"type":"string","description":"The Standard Webhooks signing secret (whsec_…); shown only this once"}},"required":["secret"]},"Telemetry":{"type":"object","properties":{"endpoint":{"type":"string"},"protocol":{"type":"string","enum":["http/protobuf","http/json"]},"sampleRate":{"type":"number"},"include":{"type":"object","properties":{"content":{"type":"boolean"}},"required":["content"]},"headers":{"type":"array","items":{"type":"string"},"description":"The names of the stored headers; their values are never returned"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"setBy":{"type":["string","null"],"description":"Who last set where it sends: \"token:<API token id>\", \"oauth:<grant id>\", \"console\" or \"operator\"; null if set before this was recorded. Revoking that token lists it"},"status":{"type":"object","properties":{"lastExportAt":{"type":["number","null"],"description":"When a node last exported spans here (recorded at most once a minute)"},"lastError":{"type":["string","null"],"description":"Why the last export failed, since the last success: an HTTP status, or how the connection failed"},"lastErrorAt":{"type":["number","null"]}},"required":["lastExportAt","lastError","lastErrorAt"]}},"required":["endpoint","protocol","sampleRate","include","headers","createdAt","updatedAt","setBy","status"]},"TelemetryInput":{"type":"object","properties":{"endpoint":{"type":"string","description":"The OTLP/HTTP traces URL spans are POSTed to (https; a collector's base URL gets /v1/traces). Needed the first time","example":"https://api.honeycomb.io/v1/traces"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers sent with each export (a collector's API key), stored encrypted and never shown again. Left out, the stored ones stay while the endpoint keeps its origin; {} removes them","example":{"x-honeycomb-team":"<key>"}},"protocol":{"type":"string","enum":["http/protobuf","http/json"],"description":"OTLP's encoding. Default http/protobuf"},"sampleRate":{"type":"number","minimum":0,"maximum":1,"description":"The share of runs traced, from 0 to 1 (default 1). A run continuing a caller's traceparent follows its sampled flag instead"},"include":{"type":"object","properties":{"content":{"type":"boolean","description":"Export what people and models wrote: prompts, replies, tool arguments and results, inputs' questions, errors' messages. Default false"}},"additionalProperties":false}},"additionalProperties":false,"description":"A field left out keeps its current value (its default the first time)"},"TelemetryTest":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"number","description":"The endpoint's HTTP status"},"error":{"type":"string"},"traceId":{"type":"string","description":"The test span's trace, to look up in your backend"},"spanId":{"type":"string"}},"required":["ok","traceId","spanId"]},"UsageWebhookSet":{"type":"object","properties":{"url":{"type":"string"},"secret":{"type":"string","description":"The Standard Webhooks signing secret (whsec_…); shown only this once"}},"required":["url"]},"UsageWebhookInput":{"type":"object","properties":{"url":{"type":"string","description":"An HTTPS URL that receives each model response's usage","example":"https://example.com/hooks/agent-usage"}},"required":["url"],"additionalProperties":false},"UsageWebhook":{"type":"object","properties":{"url":{"type":"string"},"createdAt":{"type":"number"},"setBy":{"type":["string","null"],"description":"Who last set where it sends: \"token:<API token id>\", \"oauth:<grant id>\", \"console\" or \"operator\"; null if set before this was recorded. Revoking that token lists it"}},"required":["url","createdAt","setBy"]},"Model":{"type":"object","properties":{"id":{"type":"string","description":"Pass this as `model` when creating or configuring an agent","example":"anthropic/claude-sonnet-5"},"provider":{"type":"string"},"modelId":{"type":"string"},"name":{"type":"string"},"api":{"type":"string"},"reasoning":{"type":"boolean"},"input":{"type":"array","items":{"type":"string"}},"contextWindow":{"type":"number"},"maxTokens":{"type":"number"},"cost":{"type":"object","properties":{"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"}},"required":["input","output","cacheRead","cacheWrite"],"description":"USD per million tokens"},"toolCallStreaming":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["unknown"]}],"description":"Whether the model streams tool-call arguments as it writes them. true: toolcall_delta events arrived while the call was generated in every probe, so a client can render a section as it is written. false: the arguments came in one piece when the call was complete, in at least one probe, so streaming cannot be counted on. \"unknown\": not measured"},"available":{"type":"boolean","description":"Whether this tenant has a key for the provider"}},"required":["id","provider","modelId","name","api","reasoning","input","contextWindow","maxTokens","cost","toolCallStreaming","available"]},"AgentSummary":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":["string","null"],"description":"The key it was made with (an upsert's, or POST /v1/agents' Idempotency-Key); null for one made without"},"name":{"type":"string","description":"Its name; its id when it was given none"},"type":{"type":"string"},"model":{"type":"string"},"configHash":{"type":"string","description":"A hash of the agent's configuration as its upserts set it (model, instructions, tools, builtins, name…): an upsert of the same configuration gives the same hash, changes nothing and is not counted as an agent create. Opaque; compare it, never parse it. It may change once when the runtime changes how configurations are stored"},"connected":{"type":"boolean","description":"Whether an application serving its attached tools (an SDK's upsert with tools) is connected"},"running":{"type":"boolean","description":"Whether it is loaded in a runtime node's memory now, idle or not. It does not mean a turn is going: a request's state says that"},"expiresAt":{"type":["number","null"]},"resume":{"type":["object","null"],"properties":{"failures":{"type":"number"},"after":{"type":"number"}},"required":["failures","after"],"description":"Loads of its unfinished work that failed, or found no room, and when the next may be tried: put off, doubling, at most an hour apart, never for good"},"parentAgentId":{"type":"string","description":"For a child a delegate or spawn_agent call made: the agent whose run made it"}},"required":["id","key","name","type","model","configHash","connected","running","expiresAt","resume"]},"AgentCreated":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string","description":"The agent's scoped credential for /clients routes; absent for an OAuth access token's caller, which may not hold one"},"expiresAt":{"type":["number","null"]},"configHash":{"type":"string","description":"The hash of the configuration this create or upsert asked for (see AgentSummary.configHash): the agent has it once `reconfigured` applies. The same as the agent's before: the upsert changed nothing, and was not counted as a create"},"reconfigured":{"$ref":"#/components/schemas/RequestRecord"},"prompt":{"anyOf":[{"$ref":"#/components/schemas/RequestRecord"},{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"code":{"type":"string"},"message":{"type":"string"}},"required":["status","code","message"]}},"required":["error"]}],"description":"The first prompt's request, when one was given: accepted, or refused (spend limit, capacity, model) with why, the agent made regardless; send it again with POST /v1/agents/{id}/prompt"},"warnings":{"type":"array","items":{"type":"string"},"description":"Builtins the agent has that its tenant cannot use yet, and how to fix it: web_search without a key for any of its search providers (add one with PUT /v1/providers/{provider}/key)"}},"required":["id","expiresAt","configHash"],"additionalProperties":{}},"RequestRecord":{"type":"object","properties":{"id":{"type":"string"},"method":{"type":"string","enum":["prompt","execute","status","abort","continue","steer","configure","resume"],"description":"resume: the runtime continuing a turn that waited on human input, once its inputs settled"},"state":{"type":"string","enum":["running","completed"]},"fingerprint":{"type":"string"},"startedAt":{"type":"number"},"began":{"type":"number"},"endedAt":{"type":"number"},"prompt":{"type":"string"},"code":{"type":"string"},"suspension":{"type":"string","description":"resume: the request whose turn waited on human input"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"The metadata sent with the message"},"resumes":{"type":"number","description":"Times a node resumed this run's turn after the node running it was lost (its calls in flight closed as of unknown outcome); at most 2"},"handoffs":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["retire","drain"]},"at":{"type":"number"}},"required":["reason","at"]},"description":"Times a node leaving the cluster (retire: a newer deploy replaced it; drain: it was stopped) handed this run's turn off at a step boundary, and the next owner continued it with nothing lost. Not resumes"},"steeredInto":{"type":"string","description":"A prompt with whileRunning: steer that a running turn took: that turn's request. This request completes as the turn takes the message; the turn's request has the turn's outcome (reply, output...)"},"steer":{"type":"string","enum":["accepted","queued"],"description":"A prompt with whileRunning: steer, as it was accepted: accepted, the running turn reads it after its current step; queued, no turn could take it, so it runs as a turn of its own"},"abortedAt":{"type":"number","description":"When the agent was stopped while this run was going: it ends as aborted, and is never resumed elsewhere"},"outcome":{"$ref":"#/components/schemas/Outcome"},"error":{"type":"string","description":"An ended request's error, from its outcome: the runtime's (outcome.error) or the model's (outcome.result.error). Absent when it succeeded"},"stopped":{"type":"string","enum":["input_required","spend_limit","turn_limit","agent_loop_limit"],"description":"Why an ended run stopped early (outcome.result.stopped)"},"status":{"type":"string","enum":["completed","input_required","failed"],"description":"How an ended request ended (state says only that it ended): failed when it has an error or stopped at a spend or turn limit; input_required when it waits on people. Absent while running"},"trace":{"type":"object","properties":{"traceId":{"type":"string"},"spanId":{"type":"string","description":"The run's own span"},"parentSpanId":{"type":"string","description":"The span it continues: the caller's traceparent, or the run a resume continues"},"sampled":{"type":"boolean"}},"required":["traceId","spanId","sampled"],"description":"A run's place in its trace, when the tenant exports telemetry (PUT /v1/telemetry)"}},"required":["id","method","state","fingerprint"],"description":"An upsert of an existing agent: the configure request bringing it to this configuration between its turns"},"Outcome":{"type":"object","properties":{"result":{},"error":{"type":"string"},"uncertain":{"type":"boolean"}},"description":"result.code names a run's failure where it has a name: cancelled (a stop cancelled it before it began), aborted (stopped while it ran), model_stream_stalled (its model stopped answering, past every retry), turn_limit, spend_limit, agent_loop_limit (a sub-agent's notification landed without a turn: its chain reached its wake cap), output_missing, model_key_missing, model_key_invalid. result.stopped is input_required when the turn waits on human input, listed in result.inputs. A run's result also has reply, replyIndex, files, toolErrors and toolCalls: every tool call it made (the first 100), as {tool, toolCallId?, innerCallId?, ok, code?, agentId?} (agentId: the child a delegate or spawn_agent call ran), without arguments or results. result.output is a structured answer, for a prompt sent with output. result.usage.subagentCostUsd is what its children spent, and result.usage.imageCostUsd what its generate_image calls spent. result.servedModel is the model that made its last response (provider/model-id); result.modelError, when a model call failed it, says how: {errorClass, providerStatus?, retryable, model} (ModelFailure)"},"AgentInput":{"type":"object","properties":{"mcp":{"type":"object","properties":{"tools":{"type":"array","items":{}}},"required":["tools"],"description":"The application's attached MCP server: its tools/list, whose tools the agent calls back through the application's connection. The SDKs send it"},"definition":{"type":"string","description":"Make the agent from this definition (GET /v1/definitions). It supplies the model, system prompt, thinking level, fileTools and tool sources; name, type, ttlSeconds, mounts and initialMessages given here override its defaults. model, thinkingLevel, maxOutputTokens, temperature, fileTools, codeMode and runLimits given here are the agent's own: applying the definition later keeps them. systemPrompt cannot be given with a definition; use systemPromptAppend"},"name":{"type":"string"},"type":{"type":"string"},"model":{"type":"string","description":"A model id from GET /v1/models; the runtime default when omitted"},"systemPrompt":{"type":"string"},"systemPromptAppend":{"type":"string","maxLength":32000,"description":"Text after the system prompt, e.g. per-conversation context. The agent's own: applying its definition replaces the prompt and keeps this"},"thinkingLevel":{"type":"string","enum":["off","minimal","low","medium","high","xhigh","max"]},"maxOutputTokens":{"$ref":"#/components/schemas/MaxOutputTokens"},"temperature":{"$ref":"#/components/schemas/Temperature"},"initialMessages":{"type":"array","items":{},"description":"History to begin with (a conversation from elsewhere): Pi user, assistant and toolResult messages, and compactionSummary messages, the last of which stands in for everything before it. Only when the agent is made; at most 16 MB of JSON. See the multi-user guide"},"importMessages":{"type":"object","properties":{"format":{"type":"string","enum":["anthropic","openai-responses","openai-chat"],"description":"anthropic: Messages API messages; openai-responses: Responses API input items; openai-chat: Chat Completions messages"},"messages":{"type":"array","items":{}},"model":{"type":"string","description":"The model that wrote the assistant turns, as provider/model-id: its signed thinking or encrypted reasoning is sent back to that same model; any other model gets reasoning as text, or none","example":"anthropic/claude-sonnet-5"}},"required":["format","messages"],"description":"History to begin with in another API's format, with its tool calls and results, converted to Pi messages (initialMessages; not both). Images must be base64 or data: URLs; system and developer messages are left out (the agent's prompt replaces them). Only when the agent is made"},"fileTools":{"type":"boolean","description":"false: the model gets no file tools (read, write, edit, ls, glob, grep), only present_file; the mounts stay open to fs in js_exec, attachments and tool outputs. For applications with file tools of their own"},"codeMode":{"type":"boolean","description":"false: no js_exec (code mode). The model calls every tool directly, and the system prompt carries only the runtime text those tools need: for an agent with no tools (with fileTools: false too, and no builtins or tool sources), only the application's instructions and a short note on who sent each message. For a tool-less agent, such as a classifier. Best set when the agent is made: changed later, its tools change, while a conversation under way keeps the runtime text it began with"},"ttlSeconds":{"type":["integer","null"],"description":"Agent lifetime: 60 to 31622400 seconds, or null to live until deleted. Default: until deleted for an agent made with an Idempotency-Key, 86400 for one made without"},"idleTtlSeconds":{"type":["integer","null"],"minimum":60,"maximum":31622400,"description":"Instead of ttlSeconds: the agent lives this long (60 to 31622400 seconds) from its latest run, so one in use is kept and one left idle expires. Not with ttlSeconds"},"mounts":{"type":"array","items":{"$ref":"#/components/schemas/MountInput"},"description":"Volumes for the agent's file tools. Its own workspace volume is at /workspace beside them unless they include {workspace: false} or a mount at /workspace; {workspace: true, path?} places it. The first is where relative paths resolve"},"remount":{"type":"boolean","description":"An upsert of an existing agent: true sets the mounts given, between its turns, where other mounts are a 409"},"subject":{"type":"string","description":"Who the agent acts for (a user id in your app): the `sub` of the identity tokens its tool servers with auth \"runtime\" get. Set only here"},"context":{"type":"object","additionalProperties":{},"description":"Claims your tool servers need (org, workspace, thread…), carried as `ctx` in its identity tokens; at most 4 KB. Set only here"},"builtins":{"type":"array","items":{"$ref":"#/components/schemas/Builtin"},"maxItems":8,"description":"Tools the runtime answers itself (web_fetch, web_search, schedule, ask_user, delegate, generate_image, agents), for an agent without a definition; one made from a definition has its definition's. An upsert without builtins leaves the agent none"},"delegate":{"$ref":"#/components/schemas/DelegateSettings"},"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/InlineMcpServerInput"},"maxItems":64,"description":"Remote MCP servers whose tools the runtime calls for the agent, for an agent without a definition; one made from a definition has its definition's. No credentials: auth \"runtime\" or none. An upsert without mcpServers leaves the agent none"},"keyScope":{"type":"string","description":"A key scope (PUT /v1/key-scopes/{scope}/providers/{provider}) whose keys the agent's model calls use first, before the tenant's own","example":"org_abc123"},"spendLimit":{"$ref":"#/components/schemas/SpendLimitInput"},"runLimits":{"$ref":"#/components/schemas/RunLimits"},"modelHeaders":{"$ref":"#/components/schemas/ModelHeaders"},"prompt":{"$ref":"#/components/schemas/PromptInput"}},"additionalProperties":false},"MaxOutputTokens":{"type":"integer","minimum":1,"description":"The most the model writes in one response, at most its own maximum (maxTokens in GET /v1/models); default that maximum. A response that reaches it ends with stopReason \"length\". A Claude model on a thinking budget gets the budget on top; elsewhere reasoning counts toward it. Compaction summaries keep the runtime's own"},"Temperature":{"type":"number","minimum":0,"maximum":2,"description":"Sampling temperature, 0 to 2; default the provider's. Lower is more deterministic. 400 for a model that takes none: Claude Opus 4.7 and later, Sonnet 5.5 and Fable models, models that always reason (o-series, GPT-5), and any reasoning model at a thinkingLevel other than off. Compaction summaries keep the runtime's own"},"MountInput":{"anyOf":[{"$ref":"#/components/schemas/Mount"},{"$ref":"#/components/schemas/WorkspaceMount"}]},"Mount":{"type":"object","properties":{"volumeId":{"type":"string"},"path":{"type":"string","description":"Where the agent's file tools see the volume, e.g. /workspace"},"mode":{"type":"string","enum":["ro","rw"]},"subpath":{"type":"string","description":"Mount only this directory of the volume"},"notify":{"type":"boolean","description":"Prompt the agent when others change files under this mount"}},"required":["volumeId","path","mode"]},"WorkspaceMount":{"type":"object","properties":{"workspace":{"type":"boolean"},"path":{"type":"string","description":"With true: where it is mounted, absolute and normalized (default /workspace), e.g. /scratch beside a project volume at /workspace","example":"/scratch"}},"required":["workspace"],"additionalProperties":false,"description":"The agent's own workspace volume, where attachments, tool outputs and scratch files go. It is mounted at /workspace beside the mounts given (last) unless they leave it out: true places it at this position (at `path`), false leaves it out, and a mount given at /workspace takes its place"},"Builtin":{"type":"string","enum":["web_fetch","web_search","schedule","ask_user","delegate","generate_image","agents"],"description":"agents: sub-agents in the background (spawn_agent, wait_agent, list_agents), with the delegate settings"},"DelegateSettings":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentTarget"},"maxItems":32,"description":"Who the model may delegate to: definitions (a new child agent for each call) and existing agents by key"},"instructions":{"type":"boolean","description":"Let the model start a child with instructions of its own instead, on its own model"},"maxDepth":{"type":"integer","minimum":1,"maximum":5,"description":"How deep delegation may go: a child is depth 1, its child depth 2. Default 2"},"maxParallel":{"type":"integer","minimum":1,"maximum":16,"description":"delegate calls of one run in flight at once (more wait their turn), and the agent's background sub-agents running at once (spawn_agent past it is refused). Default 4"}},"additionalProperties":false,"description":"With the delegate or agents builtin: who the agent may hand tasks to. Not with a definition, whose own it takes"},"AgentTarget":{"anyOf":[{"type":"string","description":"A definition's key or id; the model sees it by that name"},{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","description":"What the model calls it; default: the definition's or agent's key"},"definition":{"type":"string","description":"A definition's key or id"},"agent":{"type":"string","description":"An existing agent's key. The agent keeps its history across calls; a definition makes a new child each call"},"description":{"type":"string","maxLength":1000,"description":"What it is for, for the model; default: the definition's description"}},"additionalProperties":false}]},"InlineMcpServerInput":{"type":"object","properties":{"name":{"type":"string","description":"Its tools reach the model as <name>__<tool>: 1–32 letters and digits, single underscores between them"},"url":{"type":"string","description":"The server's Streamable HTTP (or older SSE) endpoint; https, on a public address"},"allowTools":{"type":"array","items":{"type":"string"},"maxItems":512,"description":"Only these of its tools"},"denyTools":{"type":"array","items":{"type":"string"},"maxItems":512,"description":"None of these of its tools"},"exposure":{"type":"string","enum":["direct","codemode","both"],"description":"How the model calls its tools: directly, from js_exec (the default), or both"},"timeoutMs":{"type":"integer","minimum":1000,"maximum":1200000,"description":"How long a call may go without an answer; default 60000. Each progress notification the server sends restarts it, up to 1200000 in all"},"audience":{"type":"string","description":"With auth \"runtime\": the tokens' aud, when not the server's url (behind a proxy, say): a URL on its origin, or a name that stays when the server moves, urn:camelrun:<tenant>:<name>"},"approval":{"type":"object","properties":{"default":{"type":"string","enum":["never","always","destructive"],"description":"never (the default), always, or destructive: tools annotated destructiveHint (MCP), operations other than GET, HEAD and OPTIONS (OpenAPI)"},"tools":{"type":"object","additionalProperties":{"type":"string","enum":["never","always"]},"description":"Per tool, by its own name: overrides the default"}},"additionalProperties":false,"description":"Which tools the user approves before each call. Those tools are declared to the model directly; an approved call carries _meta[\"agent-runtime/approval\"] and an approval claim in its identity token"},"fileArguments":{"type":"string","enum":["on","off"],"description":"Whether the model may send the agent's files to its tools ({\"$file\": path}), and the runtime saves files they link to. Default on with auth \"runtime\", off otherwise: another party's server could be sent any file the agent can read"},"auth":{"type":"object","properties":{"type":{"type":"string","enum":["runtime"]}},"required":["type"],"additionalProperties":{},"description":"Each request carries a JWT the runtime signs, naming the tenant, agent, subject, context and actor (no definition); verify it against /.well-known/jwks.json. The only auth an agent's own server takes"}},"required":["name","url"],"additionalProperties":{},"description":"An MCP server of the agent's (or run's) own, as a definition's is, but with no credentials: no headers and no bearer token (a 400 says to use a definition, which seals them once). Not listed when saved: a server that cannot be listed shows in a run's sourceErrors"},"SpendLimitInput":{"type":"object","properties":{"usd":{"type":"number","minimum":0,"maximum":1000000}},"required":["usd"],"additionalProperties":false,"description":"The most the agent may spend on model calls (their token cost, compaction included) from when this is set: a new value starts counting from zero. At it, new prompts get 402 and a running turn ends with stopped \"spend_limit\""},"RunLimits":{"type":"object","properties":{"maxResponses":{"type":"integer","minimum":1,"maximum":1000000,"description":"Model responses one run may make, compaction summaries included; default and at most the runtime's maximum (1,000 unless its operator set another)"},"maxSeconds":{"type":"integer","minimum":1,"maximum":31536000,"description":"Seconds one run may take from when it began; default and at most the runtime's maximum (7,200, 2 hours, unless its operator set another). A turn still inside a model request or tool call 60 seconds past it is aborted then, with stopped \"turn_limit\""},"firstTokenSeconds":{"type":"integer","minimum":1,"maximum":3600,"description":"Seconds one model request may wait for the model's first token (text, thinking or a tool call) before it fails as stalled and is retried; default the runtime's (120, or 300 for a reasoning model at thinkingLevel high and up)"},"idleSeconds":{"type":"integer","minimum":1,"maximum":3600,"description":"Seconds a model response may go quiet once it streams before it fails as stalled and is retried; default the runtime's (45)"},"contextTokens":{"type":"integer","minimum":20000,"description":"The most context one model request carries, in tokens: older context is summarized (compacted) before a request would pass it, starting in the background somewhat below it. Default the model's context window, and never above it. At least 20,000. A long-lived agent on a large-window model costs less per request with a lower one, since each request reads its whole context"}},"additionalProperties":false,"description":"The most one run may take (model responses, seconds); an agent from a definition gets the definition's unless this is given"},"ModelHeaders":{"type":"object","additionalProperties":{"type":"string"},"description":"Non-secret headers sent on each of the agent's model calls, after a key scope entry's, e.g. cf-aig-metadata. At most 20 and 8 KB; never authorization, x-api-key, x-goog-api-key, cf-aig-authorization, chatgpt-account-id, x-agent-runtime-identity, x-amz-* or transport headers"},"PromptInput":{"type":"object","properties":{"text":{"type":"string","description":"The message. It may be left out when the message attaches audio, whose transcript is then the message"},"actor":{"type":"string","description":"Who is acting in this turn (a user id in your app): `act` in its tools' identity tokens"},"from":{"type":"object","properties":{"id":{"type":"string","description":"The sender's id in your app; the model may rely on it"},"name":{"type":"string","description":"Display name, chosen by the sender"},"username":{"type":"string","description":"Handle, chosen by the sender"}},"required":["id"],"additionalProperties":false,"description":"Who sent this message. The model sees it in a block only the runtime can write; `from.id` is also the turn's actor unless `actor` is given"},"requestId":{"type":"string","description":"Idempotency: retrying with the same id returns the same request. The user message records it, so a UI can match its own bubble"},"allowDisconnected":{"type":"boolean","description":"Run even though the agent's tools need its application and none is connected (else 409 APPLICATION_NOT_CONNECTED): its calls then fail as not connected"},"whileRunning":{"type":"string","enum":["queue","steer"],"description":"What happens if the agent is working on a turn when this arrives. queue (default): it runs as the next turn. steer: the running turn takes it after its current step. The 202 says so at once (steer: \"accepted\"; \"queued\" when no turn could take it), and this request completes as soon as the turn takes the message (steeredInto names the turn, whose own request has its outcome; a steer_taken event marks it), so steered messages never wait for the turn's end, nor count against the agent's queue once taken. If the turn ends first, it runs as a turn of its own. With no turn running, both start one"},"spendLimit":{"allOf":[{"$ref":"#/components/schemas/SpendLimitInput"},{"description":"This run's own budget in USD: it ends before its next model request once it has spent this. The agent's spendLimit is unchanged and counts the run too"}]},"runLimits":{"type":"object","properties":{"maxResponses":{"type":"integer","minimum":1},"maxSeconds":{"type":"integer","minimum":1}},"additionalProperties":false,"description":"This run's own limits: at most this many model responses, or seconds. They only lower the agent's runLimits and the runtime's; at one, the run ends with stopped \"turn_limit\""},"output":{"type":"object","properties":{"schema":{"type":"object","additionalProperties":{},"description":"A JSON Schema for an object (type: \"object\"; at most 64 KB)","example":{"type":"object","properties":{"sentiment":{"type":"string","enum":["positive","neutral","negative"]}},"required":["sentiment"]}}},"required":["schema"],"additionalProperties":false,"description":"Structured output: the agent ends this run by calling a final_output tool whose arguments are the schema, checked against it (a call that does not fit goes back to the model with what is wrong). The run's outcome.result.output is that object. A model that answers in text instead is asked once more, with a reminder; a run that still ends without an output fails with code output_missing. The tool stays declared until a prompt without output. Not with whileRunning: steer"},"history":{"type":"string","enum":["full","none"],"description":"What the model sees of the agent's history in this run. full (default): all of it. none: only the system prompt (instructions, tools) and this message, as a new conversation would, without making an agent. The run is still recorded in the history (its user message carries history: \"none\"), and later runs that do not say none see it. Not with whileRunning: steer"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value data about this message (its source, a client-side id): at most 16 keys of 1–64 characters, values of at most 512. Kept on the user message (history, events, snapshots) and the request, and sent with its run's webhook events; never shown to the model","example":{"source":"web","clientMessageId":"m_123"}},"files":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"path":{"type":"string","description":"A file in the agent's mounts, e.g. one uploaded with PUT /v1/agents/{id}/uploads/{requestId}/{name}"},"transcribe":{"type":"boolean","description":"Whether this file is transcribed for the model (audio only): default true for audio (an audio/* content type), false for anything else. See the voice and audio guide"}},"required":["path"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string"},"data":{"type":"string","description":"The file's bytes, base64: at most 4 MiB across a message's inline files"},"contentType":{"type":"string"},"transcribe":{"type":"boolean","description":"Whether this file is transcribed for the model (audio only): default true for audio (an audio/* content type), false for anything else. See the voice and audio guide"}},"required":["data"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","description":"An https URL the runtime fetches the file from (public addresses only; at most 64 MiB)"},"name":{"type":"string"},"contentType":{"type":"string"},"transcribe":{"type":"boolean","description":"Whether this file is transcribed for the model (audio only): default true for audio (an audio/* content type), false for anything else. See the voice and audio guide"}},"required":["url"],"additionalProperties":false}]},"description":"Attached files (at most 20): saved in the agent's workspace under uploads/<requestId>/, named in the message, and shown natively (images, PDFs) to models that take them. Audio is transcribed before the request is accepted, and the model reads the transcript"}},"description":"A first prompt, as POST /v1/agents/{id}/prompt takes it, sent once the agent is made: it runs as soon as the agent has started, so a new conversation needs one call. Give it a requestId: a retry of the create (same Idempotency-Key) with the same requestId makes no second agent and sends no second prompt"},"AgentDetail":{"allOf":[{"$ref":"#/components/schemas/AgentSummary"},{"type":"object","properties":{"definition":{"type":"object","properties":{"id":{"type":"string"},"revision":{"type":"number"}},"required":["id","revision"],"description":"The definition the agent was made from, and the revision it has"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolDefinition"},"description":"The tools your application declared, which it answers"},"toolSources":{"type":"array","items":{"$ref":"#/components/schemas/ToolSource"},"description":"Every source of the agent's tools, in order of precedence, and what each offers the model"},"mounts":{"type":"array","items":{"$ref":"#/components/schemas/Mount"}},"systemPrompt":{"type":"string"},"systemPromptAppend":{"type":"string"},"fileTools":{"type":"boolean","enum":[false],"description":"Present when the model gets no file tools but present_file"},"codeMode":{"type":"boolean","enum":[false],"description":"Present when the agent has no js_exec, and the model calls every tool directly"},"keyScope":{"type":["string","null"],"description":"The key scope its model calls take keys from first"},"modelHeaders":{"allOf":[{"$ref":"#/components/schemas/ModelHeaders"},{"type":["object","null"]}]},"builtins":{"type":"array","items":{"$ref":"#/components/schemas/Builtin"},"description":"The tools the runtime answers itself: its own, or its definition's"},"delegate":{"allOf":[{"$ref":"#/components/schemas/DelegateSettings"},{"type":["object","null"],"description":"Who it may delegate to, with the delegate or agents builtin"}]},"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/McpServer"},"description":"Its remote MCP servers: its own, or its definition's (without credentials' values)"},"parentRunId":{"type":"string","description":"For a child a delegate or spawn_agent call made: the run of parentAgentId that made it"},"spendLimit":{"type":["object","null"],"properties":{"usd":{"type":"number"},"spent":{"type":"number","description":"Model spend since the limit was set"}},"required":["usd","spent"]},"runLimits":{"allOf":[{"$ref":"#/components/schemas/RunLimits"},{"type":["object","null"],"description":"Its own run limits, as set; null: the runtime's"}]},"maxOutputTokens":{"allOf":[{"$ref":"#/components/schemas/MaxOutputTokens"},{"type":["integer","null"],"description":"The most its model writes in one response, as set; null: the model's maximum"}]},"temperature":{"allOf":[{"$ref":"#/components/schemas/Temperature"},{"type":["number","null"],"description":"Its model's sampling temperature, as set; null: the provider's default"}]},"forkedFrom":{"$ref":"#/components/schemas/ForkedFrom"},"busy":{"type":"boolean","description":"Whether the agent has a run open: one going (activeRun) or queued (queuedRuns). From its request records, as its state and a status request say it too"},"activeRun":{"type":["string","null"],"description":"The run that has begun and not ended, if any"},"queuedRuns":{"type":"integer","description":"Runs accepted and waiting behind it (prompts, steered messages not yet read, continues, executions, resumes)"},"cursor":{"type":"number"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"data":{}},"required":["id"]}},"requests":{"type":"array","items":{"$ref":"#/components/schemas/RequestRecord"}}},"required":["tools","toolSources","mounts","systemPrompt","keyScope","modelHeaders","builtins","delegate","mcpServers","spendLimit","runLimits","maxOutputTokens","temperature","busy","activeRun","queuedRuns","cursor","events","requests"]}]},"ToolDefinition":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","additionalProperties":{},"description":"JSON Schema of the arguments"},"exposure":{"type":"string","enum":["direct","codemode","both"]},"executionMode":{"type":"string","enum":["sequential","parallel"]}},"required":["name","description","parameters"]},"ToolSource":{"type":"object","properties":{"kind":{"type":"string","enum":["channel","application","files","builtin","mcp","openapi"],"description":"channel: the channel's send_message; application: the tools your application answers; files: file tools over the agent's mounts; builtin, mcp, openapi: the definition's sources, which the runtime calls itself"},"name":{"type":"string","description":"The built-in's, MCP server's or OpenAPI source's name; the kind for the others"},"status":{"type":"string","enum":["listed","unlisted","error"],"description":"unlisted: an MCP server this node has not listed yet (see refresh); error: listing it failed, so the model has none of its tools"},"error":{"type":"string"},"listedAt":{"type":"number","description":"When an MCP server was last listed, or its listing failed"},"connected":{"type":"boolean","description":"application: whether your application is connected to answer its tools"},"url":{"type":"string"},"exposure":{"type":"string","enum":["direct","codemode","both"],"description":"The source's configured exposure; each tool shows the one it has"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"exposure":{"type":"string","enum":["direct","codemode","both"]},"executionMode":{"type":"string","enum":["sequential","parallel"]},"parameters":{"type":"object","additionalProperties":{},"description":"JSON Schema of the arguments, with schemas=true"},"excluded":{"type":"string","description":"Why the model does not get this tool (a name taken by an earlier source, or the catalog's limits); absent when it does"}},"required":["name","description"]}}},"required":["kind","name","status","tools"]},"McpServer":{"type":"object","properties":{"name":{"type":"string","description":"Its tools reach the model as <name>__<tool>: 1–32 letters and digits, single underscores between them"},"url":{"type":"string","description":"The server's Streamable HTTP (or older SSE) endpoint; https, on a public address"},"allowTools":{"type":"array","items":{"type":"string"},"maxItems":512,"description":"Only these of its tools"},"denyTools":{"type":"array","items":{"type":"string"},"maxItems":512,"description":"None of these of its tools"},"exposure":{"type":"string","enum":["direct","codemode","both"],"description":"How the model calls its tools: directly, from js_exec (the default), or both"},"timeoutMs":{"type":"integer","minimum":1000,"maximum":1200000,"description":"How long a call may go without an answer; default 60000. Each progress notification the server sends restarts it, up to 1200000 in all"},"audience":{"type":"string","description":"With auth \"runtime\": the tokens' aud, when not the server's url (behind a proxy, say): a URL on its origin, or a name that stays when the server moves, urn:camelrun:<tenant>:<name>"},"approval":{"type":"object","properties":{"default":{"type":"string","enum":["never","always","destructive"],"description":"never (the default), always, or destructive: tools annotated destructiveHint (MCP), operations other than GET, HEAD and OPTIONS (OpenAPI)"},"tools":{"type":"object","additionalProperties":{"type":"string","enum":["never","always"]},"description":"Per tool, by its own name: overrides the default"}},"additionalProperties":false,"description":"Which tools the user approves before each call. Those tools are declared to the model directly; an approved call carries _meta[\"agent-runtime/approval\"] and an approval claim in its identity token"},"fileArguments":{"type":"string","enum":["on","off"],"description":"Whether the model may send the agent's files to its tools ({\"$file\": path}), and the runtime saves files they link to. Default on with auth \"runtime\", off otherwise: another party's server could be sent any file the agent can read"},"headerNames":{"type":"array","items":{"type":"string"},"description":"Headers the server gets; their values are never returned"},"auth":{"$ref":"#/components/schemas/SourceAuth"}},"required":["name","url"]},"SourceAuth":{"type":"object","properties":{"type":{"type":"string","enum":["bearer","runtime"]}},"required":["type"]},"ForkedFrom":{"type":"object","properties":{"agentId":{"type":"string","description":"The agent it was forked from"},"atMessage":{"type":["number","null"],"description":"The history index of that agent's last message it began with; null: it began with none"}},"required":["agentId","atMessage"],"description":"For a fork (POST /v1/agents/{id}/fork): the agent and message it was forked from"},"AgentCredentials":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string","description":"The agent's scoped credential for /clients routes"},"expiresAt":{"type":["number","null"]},"configHash":{"type":"string","description":"The configuration it has (see AgentSummary.configHash)"}},"required":["id","token","expiresAt"]},"AgentForked":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string","description":"The fork's scoped credential for /clients routes; absent for an OAuth access token's caller, which may not hold one"},"expiresAt":{"type":["number","null"]},"forkedFrom":{"$ref":"#/components/schemas/ForkedFrom"}},"required":["id","expiresAt","forkedFrom"]},"AgentForkInput":{"type":"object","properties":{"key":{"type":"string","description":"The fork's own key, like a create's Idempotency-Key (that header is taken too): a retry with it returns the same fork, and agents.get finds it. Default: a new key, as a create without one"},"name":{"type":"string","description":"Default: the source's name, with (fork)"},"atMessage":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"Where the fork's history ends. A history index: that message, and the tool results that answer it. A request id: the whole turn that request ran. Default: the last turn that ended, never one still running or waiting on input (409 FORK_POINT_RUNNING for a message in such a turn)"},"ttlSeconds":{"type":["integer","null"],"description":"The fork's lifetime: 60 to 31622400 seconds, or null to live until deleted. Default: until deleted with a key, 86400 without"},"subject":{"type":"string","description":"Who the fork acts for, instead of the source's subject (fixed once it is made, as at a create)"},"context":{"type":"object","additionalProperties":{},"description":"Context for the fork's tool servers' identity tokens, instead of the source's (fixed once it is made, as at a create)"},"systemPromptAppend":{"type":"string","maxLength":32000,"description":"The fork's own text after the system prompt (e.g. its conversation's context), instead of the source's; \"\" removes it"},"modelHeaders":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"The fork's own headers on each model call (e.g. its conversation for attribution), instead of the source's; null removes them"}}},"EventPoll":{"type":"object","properties":{"cursor":{"type":"number","description":"Send as Last-Event-ID on the next poll"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"data":{}},"required":["id"]}}},"required":["cursor","events"]},"SessionState":{"type":"object","properties":{"cursor":{"type":"number","description":"The agent's latest event id: a stream opened with it as Last-Event-ID continues from here"},"requests":{"type":"array","items":{"$ref":"#/components/schemas/RequestRecord"},"description":"Recent requests (the running ones and the latest settled), with their outcomes"},"busy":{"type":"boolean","description":"Whether the agent has a run open: one going (activeRun) or queued (queuedRuns). From its request records, as its state and a status request say it too"},"activeRun":{"type":["string","null"],"description":"The run that has begun and not ended, if any"},"queuedRuns":{"type":"integer","description":"Runs accepted and waiting behind it (prompts, steered messages not yet read, continues, executions, resumes)"},"resume":{"type":"object","properties":{"failures":{"type":"number"},"after":{"type":"number"}},"required":["failures","after"],"description":"For an agent no node holds, whose unfinished work's loads are put off: how many times, and until when"}},"required":["cursor","requests","busy","activeRun","queuedRuns"]},"HistoryPage":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number","description":"The message's index in the agent's history"},"message":{}},"required":["index"]},"description":"Whole turns, oldest first"},"next":{"type":["number","null"],"description":"Pass as before for the older page; null at the start of the history"},"total":{"type":"number","description":"Messages in the history, the running turn's included"},"split":{"type":"boolean","enum":[true],"description":"One turn alone was larger than a page (about 4 MB), so this page starts inside it"}},"required":["entries","next","total"]},"History":{"type":"object","properties":{"messages":{"type":"array","items":{}}},"required":["messages"],"additionalProperties":{}},"BrowserToken":{"type":"object","properties":{"token":{"type":"string","description":"Send as Authorization: Bearer <token>, never in a URL"},"expiresAt":{"type":"number"},"agentId":{"type":"string"},"url":{"type":"string","description":"Where the browser reaches the runtime"}},"required":["token","expiresAt","agentId"]},"BrowserTokenInput":{"type":"object","properties":{"ttlSeconds":{"type":"integer","minimum":5,"maximum":3600,"description":"How long it lives: 5 to 3600 seconds, default 900. Nothing revokes it sooner"},"scopes":{"type":"array","items":{"type":"string","enum":["events","state","history","inputs","children"]},"description":"What it reads of the agent: GET /v1/agents/{id}/<scope>. Default events, state, history and inputs. children: it reads the same of the agent's background sub-agents (spawn_agent's), by their ids"},"events":{"type":"array","items":{"type":"string"},"maxItems":64,"description":"Only these event types (message_update, tool_execution_end, ...) reach it; default every one but the runtime's own (codemode, compaction_usage, spend_limit_reached, turn_limit_reached). Outcomes (response) and snapshots always do, an outcome only as whether and why its run stopped"},"redact":{"type":"array","items":{"type":"string","enum":["usage.cost"]},"description":"Fields it does not see: usage.cost, a response's provider cost, in messages, snapshots and history"},"subject":{"type":"string","maxLength":200,"description":"Whom it is for, in your app (a user id)"}}},"Aborted":{"type":"object","properties":{"aborted":{"type":"boolean","enum":[true]},"cancelled":{"type":"array","items":{"type":"string"},"description":"The ids of the queued runs the stop cancelled"}},"required":["aborted","cancelled"]},"AbortInput":{"type":"object","properties":{"queued":{"type":"string","enum":["cancel","keep"],"description":"cancel (default): the runs queued behind the running one (prompts, steered messages not yet read, continues, executions) are cancelled too, each ending with code cancelled, so nothing runs after the stop. keep: only the running turn is stopped, and the next queued run starts"},"children":{"type":"string","enum":["abort","keep"],"description":"abort (default): the agent's running background sub-agents (spawn_agent) are aborted too, and their notifications follow with status aborted. keep: they go on"}},"additionalProperties":false},"Upload":{"type":"object","properties":{"path":{"type":"string","description":"Where the agent sees the file: attach it as {path}"},"version":{"type":"number"},"size":{"type":"number"},"updatedAt":{"type":"number"},"by":{"type":"string"},"contentType":{"type":"string"}},"required":["path","version","size","updatedAt","contentType"]},"ConfigureInput":{"type":"object","properties":{"requestId":{"type":"string","minLength":1},"model":{"type":"string","description":"Model id from GET /v1/models"},"systemPrompt":{"type":"string","minLength":1,"maxLength":32000},"systemPromptAppend":{"type":"string","maxLength":32000,"description":"Text after the system prompt; empty removes it"},"thinkingLevel":{"type":"string","enum":["off","minimal","low","medium","high","xhigh","max"]},"maxOutputTokens":{"type":["integer","null"],"minimum":1,"description":"Replaces the most its model writes in one response; null removes it (the model's maximum)"},"temperature":{"type":["number","null"],"minimum":0,"maximum":2,"description":"Replaces its model's sampling temperature; null removes it (the provider's default). Refused (400) when the agent's model or thinking level, after this change, takes none"},"keyScope":{"type":["string","null"],"description":"The key scope its model calls take keys from first; null for the tenant's keys. Applying a definition keeps it"},"spendLimit":{"type":["object","null"],"properties":{"usd":{"type":"number","minimum":0,"maximum":1000000}},"required":["usd"],"additionalProperties":false,"description":"A new budget from now, applied at once, ahead of queued runs; null removes it"},"runLimits":{"type":["object","null"],"properties":{"maxResponses":{"type":"integer","minimum":1,"maximum":1000000,"description":"Model responses one run may make, compaction summaries included; default and at most the runtime's maximum (1,000 unless its operator set another)"},"maxSeconds":{"type":"integer","minimum":1,"maximum":31536000,"description":"Seconds one run may take from when it began; default and at most the runtime's maximum (7,200, 2 hours, unless its operator set another). A turn still inside a model request or tool call 60 seconds past it is aborted then, with stopped \"turn_limit\""},"firstTokenSeconds":{"type":"integer","minimum":1,"maximum":3600,"description":"Seconds one model request may wait for the model's first token (text, thinking or a tool call) before it fails as stalled and is retried; default the runtime's (120, or 300 for a reasoning model at thinkingLevel high and up)"},"idleSeconds":{"type":"integer","minimum":1,"maximum":3600,"description":"Seconds a model response may go quiet once it streams before it fails as stalled and is retried; default the runtime's (45)"},"contextTokens":{"type":"integer","minimum":20000,"description":"The most context one model request carries, in tokens: older context is summarized (compacted) before a request would pass it, starting in the background somewhat below it. Default the model's context window, and never above it. At least 20,000. A long-lived agent on a large-window model costs less per request with a lower one, since each request reads its whole context"}},"additionalProperties":false,"description":"Replaces the agent's run limits from its next run; null removes them (the runtime's apply). Set here on an agent from a definition, they stay when the definition is applied"},"modelHeaders":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Replaces the agent's model headers; null or {} removes them"},"builtins":{"type":"array","items":{"$ref":"#/components/schemas/Builtin"},"maxItems":8,"description":"Replaces the agent's builtins; [] removes them. Not for an agent made from a definition, whose builtins are its definition's"},"delegate":{"type":["object","null"],"properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentTarget"},"maxItems":32,"description":"Who the model may delegate to: definitions (a new child agent for each call) and existing agents by key"},"instructions":{"type":"boolean","description":"Let the model start a child with instructions of its own instead, on its own model"},"maxDepth":{"type":"integer","minimum":1,"maximum":5,"description":"How deep delegation may go: a child is depth 1, its child depth 2. Default 2"},"maxParallel":{"type":"integer","minimum":1,"maximum":16,"description":"delegate calls of one run in flight at once (more wait their turn), and the agent's background sub-agents running at once (spawn_agent past it is refused). Default 4"}},"additionalProperties":false,"description":"Replaces who the agent may delegate to (with the delegate builtin); null removes it"},"mcpServers":{"type":["array","null"],"items":{"$ref":"#/components/schemas/InlineMcpServerInput"},"maxItems":64,"description":"Replaces the agent's own MCP servers; null or [] removes them. No credentials: auth \"runtime\" or none. Not for an agent made from a definition, whose servers are its definition's"}},"additionalProperties":false,"description":"On an agent made from a definition, a model, thinkingLevel, maxOutputTokens, temperature or runLimits set here stays when the definition is applied; a systemPrompt set here is replaced by it"},"Input":{"type":"object","properties":{"id":{"type":"string"},"agent":{"type":"string"},"tenant":{"type":"string"},"requestId":{"type":"string","description":"The run that suspended waiting on it"},"toolCallId":{"type":"string"},"kind":{"type":"string","enum":["question","approval","form","url"],"description":"question: ask_user's questions; approval: a call the runtime or a tool wants approved; form: fields a tool asks for; url: a page a tool asks the user to open"},"message":{"type":"string"},"detail":{"type":"object","additionalProperties":{},"description":"question: { questions }; approval: { tool, source, arguments, argumentsHash }, built by the runtime from the real call; form: { requestedSchema }; url: { url, origin }"},"responders":{"type":"object","properties":{"audience":{"type":"array","items":{"type":"string"}}},"description":"Who may answer besides the definition's humanInput.approvers: by default the sender or actor whose message started the turn"},"state":{"type":"string","enum":["pending","answered","declined","cancelled","expired","superseded"]},"answer":{"type":"object","properties":{"action":{"type":"string","enum":["accept","decline","cancel"]},"content":{},"by":{"type":"object","additionalProperties":{}},"at":{"type":"number"}},"required":["action","by","at"]},"createdAt":{"type":"number"},"expiresAt":{"type":"number"}},"required":["id","agent","tenant","requestId","toolCallId","kind","message","detail","responders","state","createdAt","expiresAt"]},"Answered":{"type":"object","properties":{"input":{"$ref":"#/components/schemas/Input"},"request":{"allOf":[{"$ref":"#/components/schemas/RequestRecord"},{"type":["object","null"],"description":"The run resuming the turn, once the suspension's last input settled; poll it like a prompt"}]}},"required":["input","request"]},"AnswerInput":{"type":"object","properties":{"action":{"type":"string","enum":["accept","decline","cancel"]},"content":{"description":"question: { answers: { \"<question>\": \"<label>\" | [\"<label>\"] | \"<own words>\" } }; form: the fields, checked against its schema; approval decline: { reason? }"},"from":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"}},"required":["id"],"additionalProperties":false,"description":"Who is answering, in your app: checked against the input's audience and approvers (403)"},"actor":{"type":"string","description":"Who is answering (a user id in your app), when not from.id"}},"required":["action"]},"AnsweredAll":{"type":"object","properties":{"inputs":{"type":"array","items":{"$ref":"#/components/schemas/Input"}},"requests":{"type":"array","items":{"$ref":"#/components/schemas/RequestRecord"},"description":"The runs resuming turns whose last input these answers settled"}},"required":["inputs","requests"]},"AnswerInputs":{"type":"object","properties":{"answers":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AnswerInput"},{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}]},"minItems":1,"maxItems":100}},"required":["answers"]},"Schedule":{"type":"object","properties":{"id":{"type":"string"},"agent":{"type":"string"},"tenant":{"type":"string"},"text":{"type":"string"},"code":{"type":"string"},"history":{"type":"string","enum":["none"],"description":"Present when its wake-ups see no history"},"dueAt":{"type":"number"},"everySeconds":{"type":"number"},"createdAt":{"type":"number"},"failures":{"type":"number","description":"Occurrences in a row whose delivery was given up (after retries 1, 5 and 15 minutes later, or at once for a refusal a retry cannot change, like a spend limit's 402); the schedule moved on to its next one. Absent once a delivery succeeds"},"lastError":{"type":"string","description":"Why the latest delivery failed, while it is retried or since it was given up; absent once a delivery succeeds"},"lastErrorAt":{"type":"number","description":"When it failed, in epoch milliseconds"}},"required":["id","agent","tenant","dueAt","createdAt"]},"ScheduleInput":{"type":"object","properties":{"text":{"type":"string","description":"Prompt to deliver; give exactly one of text or code"},"code":{"type":"string","description":"Code to run in the sandbox with the agent's tools"},"history":{"type":"string","enum":["full","none"],"description":"For a text schedule: what the model sees of the agent's history at each wake-up, as a prompt's history. full (default): all of it. none: only the system prompt and the text, so a periodic agent does not read an ever longer history; its runs are still recorded in the history"},"at":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"ISO time or epoch milliseconds"},"inSeconds":{"type":"number"},"everySeconds":{"type":"integer","minimum":60}}},"Token":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"createdAt":{"type":"number"}},"required":["id","name","prefix","createdAt"]},"TokenCreated":{"allOf":[{"$ref":"#/components/schemas/Token"},{"type":"object","properties":{"token":{"type":"string","description":"The secret; shown only once"}},"required":["token"]}]},"TokenInput":{"type":"object","properties":{"name":{"type":"string","description":"1–80 characters"}},"required":["name"]},"SignedOut":{"type":"object","properties":{"signedOut":{"type":"integer","description":"How many console sessions ended"}},"required":["signedOut"]},"OAuthGrant":{"type":"object","properties":{"id":{"type":"string"},"clientName":{"type":"string","description":"The name the application registered with"},"login":{"type":["string","null"],"description":"Who consented, when they signed in with GitHub"},"scope":{"type":"string"},"createdAt":{"type":"number"},"usedAt":{"type":["number","null"],"description":"When it last got tokens"}},"required":["id","clientName","login","scope","createdAt","usedAt"]},"Revoked":{"type":"object","properties":{"revoked":{"type":"boolean","enum":[true]},"left":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["webhook","usage-webhook","telemetry"]},"id":{"type":"string"},"url":{"type":"string"}},"required":["kind","url"]},"description":"The webhooks and trace export this credential last pointed somewhere, which keep sending: review them, and change or delete any you do not recognize"}},"required":["revoked","left"]},"Usage":{"type":"object","properties":{"since":{"type":"number"},"totals":{"type":"object","properties":{"responses":{"type":"number"},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"cost":{"type":"number","description":"Usage cost in USD: model calls use provider-reported cost or a catalog estimate, excluding model credit funding; tool-ranking costs already include their funding"},"platformResponses":{"type":"number","description":"Responses that ran on a key that is not the tenant's own"},"platformCost":{"type":"number","description":"Cost in USD on platform keys, including configured provider credit funding costs; prepaid tenants pay it from credit"}},"required":["responses","input","output","cacheRead","cacheWrite","cost","platformResponses","platformCost"]},"days":{"type":"array","items":{"type":"object","properties":{"responses":{"type":"number"},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"cost":{"type":"number","description":"Usage cost in USD: model calls use provider-reported cost or a catalog estimate, excluding model credit funding; tool-ranking costs already include their funding"},"platformResponses":{"type":"number","description":"Responses that ran on a key that is not the tenant's own"},"platformCost":{"type":"number","description":"Cost in USD on platform keys, including configured provider credit funding costs; prepaid tenants pay it from credit"},"day":{"type":"string"},"model":{"type":"string"},"kind":{"type":"string","enum":["turn","compaction","transcription","image"],"description":"turn: the agent's own responses; compaction: summaries of older context; transcription: audio transcribed (responses counts transcriptions); image: images made (responses counts images)"}},"required":["responses","input","output","cacheRead","cacheWrite","cost","platformResponses","platformCost","day","model","kind"]}}},"required":["since","totals","days"]},"Transcription":{"type":"object","properties":{"text":{"type":"string"},"language":{"type":["string","null"],"description":"The language the provider heard (or was told), when it says"},"durationSeconds":{"type":"number","description":"Seconds of audio billed"},"model":{"type":"string","example":"openai/gpt-transcribe"},"costUsd":{"type":"number","description":"What it cost at the runtime's price: charged to prepaid credit when it ran on the platform's key"}},"required":["text","language","durationSeconds","model","costUsd"]},"TranscriptionInput":{"type":"object","properties":{"data":{"type":"string","description":"The audio's bytes, base64 (at most 25 MB decoded). Or send it as multipart/form-data, the audio in a part named file"},"url":{"type":"string","description":"An https URL to fetch the audio from (public addresses only)"},"language":{"type":"string","description":"The audio's language, ISO 639-1 (en) or a locale (pt-BR); detected when left out"},"prompt":{"type":"string","maxLength":2000,"description":"Words and spellings to expect (names, jargon), or the conversation so far: a hint to the model, at most 2,000 characters"},"keyScope":{"type":"string","description":"A key scope whose OpenAI key is used first, before the tenant's own"},"subject":{"type":"string","description":"Who it is for (a user id in your app): usage.recorded's subject"},"context":{"type":"object","additionalProperties":{},"description":"Your claims (org, workspace…), carried as usage.recorded's context; at most 4 KB"},"actor":{"type":"string","description":"Who asked (a user id in your app): usage.recorded's actor"}},"additionalProperties":false},"TranscriptionForm":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The audio: Ogg (Opus, Vorbis), WebM, MP3, M4A/MP4, WAV or FLAC; at most 25 MB and 30 minutes"},"language":{"type":"string","description":"The audio's language, ISO 639-1 (en) or a locale (pt-BR); detected when left out"},"prompt":{"type":"string","maxLength":2000,"description":"Words and spellings to expect (names, jargon), or the conversation so far: a hint to the model, at most 2,000 characters"},"keyScope":{"type":"string","description":"A key scope whose OpenAI key is used first, before the tenant's own"},"subject":{"type":"string","description":"Who it is for (a user id in your app): usage.recorded's subject"},"context":{"type":"string","description":"JSON of your claims, as context above"},"actor":{"type":"string","description":"Who asked (a user id in your app): usage.recorded's actor"}}},"Images":{"type":"object","properties":{"images":{"type":"array","items":{"type":"object","properties":{"contentType":{"type":"string","example":"image/png"},"width":{"type":"number"},"height":{"type":"number"},"data":{"type":"string","description":"The image, base64 (without volumeId)"},"volumeId":{"type":"string"},"path":{"type":"string","description":"Where it was saved (with volumeId): read it with GET /v1/volumes/{id}/files/{path}"},"size":{"type":"number"},"version":{"type":"number"}},"required":["contentType"]}},"model":{"type":"string","example":"openai/gpt-image-2.5-flare"},"usage":{"type":"object","properties":{"inputTokens":{"type":"number"},"outputTokens":{"type":"number"}},"required":["inputTokens","outputTokens"],"description":"The tokens the provider billed: text and images in, images out"},"costUsd":{"type":"number","description":"What it cost at the runtime's price: charged to prepaid credit when it ran on the platform's key"}},"required":["images","model","usage","costUsd"]},"ImageInput":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":32000,"description":"What to make, or how to change the images given: at most 32,000 characters"},"size":{"type":"string","enum":["1024x1024","1536x1024","1024x1536"],"description":"Square, landscape or portrait. Default 1024x1024"},"quality":{"type":"string","enum":["low","medium","high"],"description":"Default medium. Higher quality costs more (see Pricing) and takes longer"},"format":{"type":"string","enum":["png","jpeg","webp"],"description":"The images' format. Default png"},"background":{"type":"string","enum":["transparent","opaque"],"description":"transparent needs png or webp. Default: the model's choice"},"keyScope":{"type":"string","description":"A key scope whose OpenAI key is used first, before the tenant's own"},"volumeId":{"type":"string","description":"Save the images into this volume of yours (under path) and answer their paths, instead of their bytes"},"path":{"type":"string","maxLength":1000,"description":"With volumeId: the directory to save them in. Default /images"},"subject":{"type":"string","description":"Who it is for (a user id in your app): usage.recorded's subject"},"context":{"type":"object","additionalProperties":{},"description":"Your claims (org, workspace…), carried as usage.recorded's context; at most 4 KB"},"actor":{"type":"string","description":"Who asked (a user id in your app): usage.recorded's actor"},"n":{"type":"integer","minimum":1,"maximum":4,"description":"How many images to make, 1 to 4. Default 1"},"images":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"data":{"type":"string","description":"The image's bytes, base64"}},"required":["data"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","description":"An https URL to fetch the image from (public addresses only)"}},"required":["url"],"additionalProperties":false}]},"maxItems":4,"description":"Images to edit (at most 4; PNG, JPEG or WebP, 25 MB each and 50 MB in all): the prompt says how to change or combine them"},"mask":{"anyOf":[{"type":"object","properties":{"data":{"type":"string","description":"The image's bytes, base64"}},"required":["data"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","description":"An https URL to fetch the image from (public addresses only)"}},"required":["url"],"additionalProperties":false}],"description":"Where to edit the first image: transparent where it may change, an image with an alpha channel in its format and size"}},"required":["prompt"],"additionalProperties":false},"ImageForm":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":32000,"description":"What to make, or how to change the images given: at most 32,000 characters"},"size":{"type":"string","enum":["1024x1024","1536x1024","1024x1536"],"description":"Square, landscape or portrait. Default 1024x1024"},"quality":{"type":"string","enum":["low","medium","high"],"description":"Default medium. Higher quality costs more (see Pricing) and takes longer"},"format":{"type":"string","enum":["png","jpeg","webp"],"description":"The images' format. Default png"},"background":{"type":"string","enum":["transparent","opaque"],"description":"transparent needs png or webp. Default: the model's choice"},"keyScope":{"type":"string","description":"A key scope whose OpenAI key is used first, before the tenant's own"},"volumeId":{"type":"string","description":"Save the images into this volume of yours (under path) and answer their paths, instead of their bytes"},"path":{"type":"string","maxLength":1000,"description":"With volumeId: the directory to save them in. Default /images"},"subject":{"type":"string","description":"Who it is for (a user id in your app): usage.recorded's subject"},"context":{"type":"string","description":"JSON of your claims, as context in ImageInput"},"actor":{"type":"string","description":"Who asked (a user id in your app): usage.recorded's actor"},"n":{"type":"string","description":"How many images to make, 1 to 4"},"image":{"type":"string","format":"binary","description":"An image to edit; a part each, at most 4"},"mask":{"type":"string","format":"binary","description":"A mask for the first image"}},"required":["prompt"]},"Billing":{"type":"object","properties":{"billing":{"type":"string","enum":["prepaid","none"],"description":"prepaid: runs are paid from credit; none: not billed by the runtime"},"balance":{"type":"integer","description":"Credit left; at zero or below, runs are refused with 402, in micro-USD (1 USD = 1000000)"},"purchased":{"type":"integer","description":"Credit bought over the account's life, net of refunds, in micro-USD (1 USD = 1000000)"},"freeCredit":{"type":"boolean","description":"Whether the tenant has only ever had free credit, which comes with tighter limits"},"checkout":{"type":"boolean","description":"Whether credit can be bought here (POST /v1/billing/checkout)"},"busyAgents":{"$ref":"#/components/schemas/BusyAgents"},"runsPerMinute":{"type":["object","null"],"properties":{"limit":{"type":"integer","description":"Runs the account may start a minute"},"afterPurchase":{"type":["integer","null"],"description":"On free credit: what buying credit raises it to (null: no limit)"}},"required":["limit"],"description":"The account's run rate limit; null when none applies"},"startingCredit":{"type":"object","properties":{"status":{"type":"string","enum":["granted","not_eligible","not_granted","not_applicable"]},"amount":{"type":"integer","description":"The amount of starting credit actually awarded, independent of the current grant setting, in micro-USD (1 USD = 1000000)"},"cardCheck":{"type":"object","properties":{"amount":{"type":"integer","description":"Starting credit a card check would add, in micro-USD (1 USD = 1000000)"}},"required":["amount"],"description":"Present when verifying a card (POST /v1/billing/card-check) would unlock starting credit"}},"required":["status","amount"]},"month":{"type":"object","properties":{"since":{"type":"number"},"grant":{"type":"integer","description":"Granted this UTC month, in micro-USD (1 USD = 1000000)"},"purchase":{"type":"integer","description":"Bought, in micro-USD (1 USD = 1000000)"},"usage":{"type":"integer","description":"Spent on model tokens and agent time, in micro-USD (1 USD = 1000000)"},"storage":{"type":"integer","description":"Spent on storage, in micro-USD (1 USD = 1000000)"},"adjustment":{"type":"integer","description":"Adjusted by the operator, in micro-USD (1 USD = 1000000)"},"refund":{"type":"integer","description":"Refunded, in micro-USD (1 USD = 1000000)"}},"required":["since","grant","purchase","usage","storage","adjustment","refund"]},"recent":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"}},"rates":{"type":"object","properties":{"agentHour":{"type":"integer","description":"Per hour an agent spends in a turn, metered continuously, in micro-USD (1 USD = 1000000)"},"storageGbMonth":{"type":"integer","description":"Per GB-month stored, charged daily, in micro-USD (1 USD = 1000000)"},"openrouterCreditMultiplier":{"type":"number","minimum":0,"description":"Dollars paid per dollar of OpenRouter credit; applied to platform model calls and OpenRouter tool ranking, separately from the checkout fee"},"purchaseFeeBps":{"type":"integer","description":"Fee on credit purchases, in basis points"},"minPurchase":{"type":"integer","description":"Smallest purchase, in micro-USD (1 USD = 1000000)"},"maxPurchase":{"type":"integer","description":"Largest purchase, in micro-USD (1 USD = 1000000)"},"webSearch":{"type":"object","properties":{"exa":{"type":"integer","description":"Per search Exa answers, in micro-USD (1 USD = 1000000)"},"brave":{"type":"integer","description":"Per search Brave answers, in micro-USD (1 USD = 1000000)"},"parallel":{"type":"integer","description":"Per search Parallel answers, in micro-USD (1 USD = 1000000)"}},"required":["exa","brave","parallel"],"description":"Per web_search on the platform's key for the provider that answered"},"webRender":{"type":"integer","description":"Per page web_fetch has Firecrawl render on the platform's key, in micro-USD (1 USD = 1000000)"},"transcription":{"type":"integer","description":"Per minute of audio transcribed on the platform's OpenAI key (gpt-transcribe), billed per second, in micro-USD (1 USD = 1000000)"},"image":{"type":"object","properties":{"textInput":{"type":"integer","description":"Per million text tokens in, in micro-USD (1 USD = 1000000)"},"imageInput":{"type":"integer","description":"Per million image tokens in (images to edit), in micro-USD (1 USD = 1000000)"},"output":{"type":"integer","description":"Per million image tokens out, in micro-USD (1 USD = 1000000)"}},"required":["textInput","imageInput","output"],"description":"Images made on the platform's OpenAI key (gpt-image-2.5-flare), per token as the provider bills"}},"required":["agentHour","storageGbMonth","openrouterCreditMultiplier","purchaseFeeBps","minPurchase","maxPurchase","webSearch","webRender","transcription","image"],"description":"Model usage on platform keys passes through provider-reported cost (catalog estimate if unavailable) plus provider credit funding costs; tools.search's ranking by meaning is charged at cost"}},"required":["billing","balance","purchased","freeCredit","checkout","busyAgents","startingCredit","month","recent","rates"]},"BusyAgents":{"type":"object","properties":{"busy":{"type":"integer","description":"Agents busy now across the runtime: each has a run open (running or queued)"},"limit":{"type":"integer","description":"How many may be busy at once; a run past it gets 429 BUSY_AGENT_LIMIT"},"source":{"type":"string","enum":["tier","tenant","default"],"description":"tier: the usage tier's (prepaid tenants, by what they have paid); tenant: set for this tenant by the operator; default: the deployment's"},"tier":{"type":"string","description":"The usage tier, with source tier","example":"Tier 1"},"paid":{"type":"integer","description":"What the tenant has paid for credit, net of refunds (starting credit and adjustments do not count); with source tier, in micro-USD (1 USD = 1000000)"},"next":{"type":"object","properties":{"tier":{"type":"string"},"paid":{"type":"integer","description":"Paid in total that reaches it, in micro-USD (1 USD = 1000000)"},"limit":{"type":"integer","description":"Its busy-agent limit"}},"required":["tier","paid","limit"],"description":"The next tier up, if any"}},"required":["limit","source"],"description":"How many agents may be busy at once, and why: a tier moves up as soon as a payment lands"},"LedgerEntry":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["grant","purchase","usage","storage","adjustment","refund"]},"amount":{"type":"integer","description":"Positive adds credit, negative spends it, in micro-USD (1 USD = 1000000)"},"metadata":{"type":"object","additionalProperties":{},"description":"usage: one entry per UTC hour (`hour`, its start), updated until the hour ends, with tokens (micro-USD on platform keys), funding (provider credit funding adjustment in micro-USD) and activeMs; storage: day and bytes"},"createdAt":{"type":"number"}},"required":["id","kind","amount","metadata","createdAt"]},"Ledger":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"},"description":"Newest first"},"next":{"type":"integer","description":"Pass as `before` for the next page"}},"required":["entries"]},"Checkout":{"type":"object","properties":{"id":{"type":"string","description":"The Stripe Checkout session"},"url":{"type":"string","description":"Send the buyer here to pay"},"amount":{"type":"integer","description":"Credit bought, in micro-USD (1 USD = 1000000)"},"fee":{"type":"integer","description":"Fee, in micro-USD (1 USD = 1000000)"},"total":{"type":"integer","description":"Charged, in micro-USD (1 USD = 1000000)"}},"required":["id","url","amount","fee","total"]},"CheckoutInput":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid","description":"Reuse this UUID when retrying the same purchase; a different amount needs a new UUID"},"amountUsd":{"type":"number","description":"Credit to buy, in USD with at most two decimals; the fee is added on top","example":10}},"required":["amountUsd"]},"CardCheck":{"type":"object","properties":{"url":{"type":"string","description":"Send the account holder here to verify a card; nothing is charged"}},"required":["url"]},"CardCheckOutcome":{"type":"object","properties":{"status":{"type":"string","enum":["granted","not_granted","pending"],"description":"granted: starting credit was added; not_granted: this card check added none; pending: Stripe has not finished the check"},"amount":{"type":"integer","description":"Starting credit added, in micro-USD (1 USD = 1000000)"}},"required":["status","amount"]},"CardCheckConfirmInput":{"type":"object","properties":{"session":{"type":"string","description":"The Checkout session id Stripe returned to the console"}},"required":["session"],"additionalProperties":false},"StartingCreditGrantInput":{"type":"object","properties":{"tenant":{"type":"string"},"amountUsd":{"type":"number","minimum":1,"maximum":100,"description":"Starting credit to award in USD ($1–$100, whole cents), once per GitHub identity","example":5},"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Private support audit note; never included in the tenant's ledger"}},"required":["tenant","amountUsd","reason"]},"AdjustmentInput":{"type":"object","properties":{"tenant":{"type":"string"},"amount":{"type":"integer","description":"Micro-USD to add (negative to remove)"},"reason":{"type":"string","minLength":1,"maxLength":500},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,120}$","description":"Repeating an adjustment with the same key applies it once"}},"required":["tenant","amount","reason"]},"AccountDeletion":{"type":"object","properties":{"tenant":{"type":"string"},"state":{"type":"string","enum":["deleting","deleted"],"description":"deleting: the account no longer signs in or authenticates, and its data is being deleted; deleted: all of it is gone but the ledger, usage and payment records kept for accounting"},"requestedAt":{"type":"number"},"completedAt":{"type":["number","null"]},"agents":{"type":"integer","description":"While deleting: agents not yet purged"}},"required":["tenant","state","requestedAt","completedAt"]},"AccountDeletionInput":{"type":"object","properties":{"confirm":{"type":"string","description":"The account's tenant id, as GET /v1/me gives it, to confirm deleting that account"}},"required":["confirm"]},"TenantLookup":{"type":"object","properties":{"tenant":{"type":"string"},"github":{"type":["string","null"]},"googleEmail":{"type":["string","null"]},"email":{"type":["string","null"],"description":"The address it signs in with a password, if any"},"createdAt":{"type":"number"}},"required":["tenant","github","googleEmail","email","createdAt"]},"TenantCreated":{"type":"object","properties":{"tenant":{"type":"string"},"token":{"$ref":"#/components/schemas/TokenCreated"}},"required":["tenant","token"]},"TenantInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,39}$","description":"The new tenant's id: lowercase letters, digits and dashes (max 40)","example":"lab-ts-chat"},"tokenName":{"type":"string","minLength":1,"maxLength":80,"default":"api","description":"Name of the API token made with it"}},"required":["id"],"additionalProperties":false},"TenantLimits":{"type":"object","properties":{"tenant":{"type":"string"},"limits":{"type":"object","properties":{"maxStorageGb":{"type":"number"},"maxBusyAgents":{"type":"integer"},"agentCreatesPerMinute":{"type":"integer"},"runsPerMinute":{"type":"integer"},"maxRunResponses":{"type":"integer"},"maxRunSeconds":{"type":"integer"},"codeCpuMs":{"type":"integer"},"codeMaxTimeoutMs":{"type":"integer"},"codeConcurrency":{"type":"integer"}},"description":"The limits set for the tenant; those absent are its plan's"}},"required":["tenant","limits"]},"TenantLimitsInput":{"type":"object","properties":{"maxStorageGb":{"type":["number","null"],"minimum":0,"maximum":1000000,"description":"GB (10^9 bytes) the tenant may store in all, in place of its plan's (1 GB on free credit, 100 GB once it has bought credit); null returns to the plan's"},"maxBusyAgents":{"type":["integer","null"],"minimum":1,"maximum":1000000,"description":"Agents the tenant may have busy at once across the runtime, in place of its usage tier's; null returns to the tier's"},"agentCreatesPerMinute":{"type":["integer","null"],"minimum":1,"maximum":1000000,"description":"Agents the tenant may create a minute, in place of its plan's (10 on free credit, else 60); null returns to the plan's"},"runsPerMinute":{"type":["integer","null"],"minimum":1,"maximum":1000000,"description":"Runs the tenant may start a minute, in place of its plan's (60 on free credit, else 600); null returns to the plan's"},"maxRunResponses":{"type":["integer","null"],"minimum":1,"maximum":1000000,"description":"Model responses one run of the tenant's agents may make, in place of the runtime's (1,000 by default); null returns to the runtime's"},"maxRunSeconds":{"type":["integer","null"],"minimum":1,"maximum":31536000,"description":"Seconds one run of the tenant's agents may take, in place of the runtime's (7,200 by default); null returns to the runtime's"},"codeCpuMs":{"type":["integer","null"],"minimum":1,"maximum":30000,"description":"CPU milliseconds one js_exec execution may use, in place of the runtime's (2,000); null returns to the runtime's"},"codeMaxTimeoutMs":{"type":["integer","null"],"minimum":1,"maximum":120000,"description":"The longest timeoutMs (wall time) a js_exec execution may ask for, in place of the runtime's (60,000); null returns to the runtime's"},"codeConcurrency":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"js_exec executions the tenant may run at once on one node, in place of its plan's (2 on free credit, else 4); null returns to the plan's"},"codeEngine":{"type":"null","deprecated":true,"description":"Removed with QuickJS: js_exec runs on V8 only. null clears an engine set before; any other value is refused"}},"additionalProperties":false},"TenantPassword":{"type":"object","properties":{"tenant":{"type":"string"},"email":{"type":["string","null"],"description":"The sign-in address, or null once the password is removed"},"signedOut":{"type":"integer","description":"How many of the tenant's password sessions ended"}},"required":["tenant","email","signedOut"]},"TenantPasswordInput":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"description":"The address the tenant signs in with; another tenant's is refused (409)","example":"reviewer@example.com"},"password":{"type":"string","minLength":12,"maxLength":256,"description":"12 to 256 characters. Only its scrypt hash is kept"}},"required":["email","password"],"additionalProperties":false},"Channel":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"webhookUrl":{"type":"string","description":"Where the service delivers messages. Telegram's is registered for you; paste Slack's into the app's Event Subscriptions. Discord channels have none: they connect to Discord's gateway. Paste GitHub's into the app's Webhook URL"},"definition":{"type":"string","description":"The definition each conversation's agent is made from"},"access":{"type":"object","properties":{"public":{"type":"boolean"},"allow":{"type":"array","items":{"type":"string"}}},"required":["public","allow"]},"limits":{"type":"object","properties":{"perSenderPerMinute":{"type":"number"},"turnsPerDay":{"type":"number"}},"required":["perSenderPerMinute","turnsPerDay"]},"greeting":{"type":"string"},"settings":{"type":"object","additionalProperties":{}},"account":{"type":"object","additionalProperties":{"type":"string"},"description":"The bot's identity at the provider"},"credentials":{"type":"object","additionalProperties":{"type":"string"},"description":"Masked credentials"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"required":["id","tenant","type","name","access","limits","account","credentials","createdAt","updatedAt"]},"ChannelInput":{"type":"object","properties":{"type":{"type":"string","enum":["telegram","slack","discord","github","webhook","email"]},"name":{"type":"string","minLength":1,"maxLength":120},"credentials":{"type":"object","additionalProperties":{"type":"string","maxLength":4096},"description":"Telegram: { botToken }. Slack: { botToken, signingSecret }. Discord: { botToken }. GitHub: { appId, privateKey, webhookSecret }. Webhook: { secret, replyUrl? }. Email: none. Required for every other type; stored encrypted and never returned"},"definition":{"type":"string","description":"The definition each conversation's agent is made from (GET /v1/definitions); a channel created without one gets an empty definition of its own"},"access":{"type":"object","properties":{"public":{"type":"boolean","description":"Let anyone message the channel; off by default"},"allow":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":1000,"description":"Senders allowed in: user ids, or @usernames (Telegram, Discord)"}}},"limits":{"type":"object","properties":{"perSenderPerMinute":{"type":"integer","minimum":1,"maximum":600,"description":"Messages per sender per minute; default 10"},"turnsPerDay":{"type":"integer","minimum":1,"maximum":1000000,"description":"Agent turns per UTC day across the channel; default 1000"}}},"greeting":{"type":"string","minLength":1,"maxLength":4096,"description":"Reply to /start (Telegram)"},"settings":{"type":"object","additionalProperties":{},"description":"Configuration particular to the channel's type; types without any reject it. GitHub: { events, repos, ignoreDrafts, reply, authors, debounceSeconds }. Webhook: { signature, key, prompt, sender, filter, idPath, idHeader }. Email: { address?, fromName? }"}},"required":["type"]},"ChannelUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"credentials":{"type":"object","additionalProperties":{"type":"string","maxLength":4096},"description":"Telegram: { botToken }. Slack: { botToken, signingSecret }. Discord: { botToken }. GitHub: { appId, privateKey, webhookSecret }. Webhook: { secret, replyUrl? }. Email: none. Required for every other type; stored encrypted and never returned"},"definition":{"type":"string","description":"The definition each conversation's agent is made from (GET /v1/definitions); a channel created without one gets an empty definition of its own"},"access":{"type":"object","properties":{"public":{"type":"boolean","description":"Let anyone message the channel; off by default"},"allow":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":1000,"description":"Senders allowed in: user ids, or @usernames (Telegram, Discord)"}}},"limits":{"type":"object","properties":{"perSenderPerMinute":{"type":"integer","minimum":1,"maximum":600,"description":"Messages per sender per minute; default 10"},"turnsPerDay":{"type":"integer","minimum":1,"maximum":1000000,"description":"Agent turns per UTC day across the channel; default 1000"}}},"greeting":{"type":"string","minLength":1,"maxLength":4096,"description":"Reply to /start (Telegram)"},"settings":{"type":"object","additionalProperties":{},"description":"Configuration particular to the channel's type; types without any reject it. GitHub: { events, repos, ignoreDrafts, reply, authors, debounceSeconds }. Webhook: { signature, key, prompt, sender, filter, idPath, idHeader }. Email: { address?, fromName? }"}}},"Definition":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"revision":{"type":"number","description":"Increases with every change"},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"What its agents are for, in a sentence or two: shown to models as the description of each agent's MCP tool (/v1/agents/{id}/mcp)"},"model":{"type":"string","description":"A model id from GET /v1/models; the runtime default when omitted"},"systemPrompt":{"type":"string","minLength":1,"maxLength":32000},"thinkingLevel":{"type":"string","enum":["off","minimal","low","medium","high","xhigh","max"]},"maxOutputTokens":{"$ref":"#/components/schemas/MaxOutputTokens"},"temperature":{"$ref":"#/components/schemas/Temperature"},"fileTools":{"type":"boolean","description":"false: the model gets no file tools (read, write, edit, ls, glob, grep), only present_file; the mounts stay open to fs in js_exec, attachments and tool outputs. For applications with file tools of their own"},"codeMode":{"type":"boolean","description":"false: its agents get no js_exec and call every tool directly (AgentInput.codeMode)"},"limits":{"$ref":"#/components/schemas/DefinitionLimits"},"runLimits":{"allOf":[{"$ref":"#/components/schemas/RunLimits"},{"description":"The most one run may take, how long its model requests may go quiet, and how much context each carries. At maxResponses or maxSeconds, the turn ends before its next model request, after the tool calls of the response that reached it, with stopped \"turn_limit\" and code turn_limit; send another message to continue. Values above the runtime's maximums count as those. A model request that stalls (firstTokenSeconds, idleSeconds) is retried like other transient provider errors; when retries run out the run fails with code model_stream_stalled"}]},"mounts":{"type":"array","items":{"$ref":"#/components/schemas/MountInput"},"maxItems":16,"description":"Volumes for each agent's file tools, beside its own workspace at /workspace unless they include {workspace: false}"},"builtins":{"type":"array","items":{"$ref":"#/components/schemas/Builtin"},"maxItems":8,"description":"Tools the runtime answers itself: web_fetch reads a public page as text (rendering JavaScript-only pages through Firecrawl when a firecrawl key resolves); web_search searches the web through the first search provider with a key that answers (the tenant's own, else the platform's, which a prepaid tenant pays for per search at that provider's price); schedule lets the agent set, list and cancel its own wake-ups; ask_user lets the model ask the user questions, suspending its turn until they answer; generate_image makes or edits an image (OpenAI's gpt-image-2.5-flare on the tenant's OpenAI key, else the platform's, billed per token) and saves it to the workspace"},"webSearch":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"string","enum":["exa","brave","parallel"]},"minItems":1,"maxItems":3,"description":"The providers web_search tries, in order; each is skipped without a key, and the next is tried when one fails, times out or is rate limited","example":["brave"]}},"required":["providers"],"additionalProperties":false,"description":"Pin web_search to providers of your choosing instead of the runtime's order (exa, brave, parallel by default)"},"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/McpServer"}},"openApi":{"type":"array","items":{"$ref":"#/components/schemas/OpenApi"}},"delegate":{"allOf":[{"$ref":"#/components/schemas/DelegateSettings"},{"description":"With the delegate or agents builtin: who the model may hand tasks to, and how deep and wide. See the multi-agent guide"}]},"humanInput":{"type":"object","properties":{"expiresInSeconds":{"type":"integer","minimum":60,"maximum":2592000,"description":"How long an input waits for an answer: 7 days by default, at most 30, and never past the agent's own expiry"},"onExpire":{"type":"string","enum":["close","resume"],"description":"close (default): an expired input closes its call and the turn without the model; resume: the model is told and continues"},"approvers":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Who may answer any input besides the person whose message started the turn: actors, or channel senders like slack:U0123"}},"additionalProperties":false,"description":"Questions, approvals and setup steps the agent's turns wait on"},"applyOnUpdate":{"type":"boolean","description":"true: every save that makes a new revision (an upsert that changes it, or a PATCH) also applies it to every live agent made from the definition, as apply: \"all\" does, and answers with applied. Default false: only new agents get a new revision"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"},"warnings":{"type":"array","items":{"type":"string"},"description":"On a save: builtins its agents could not use yet, and how to fix it: web_search without a key for any of its search providers (add one with PUT /v1/providers/{provider}/key), generate_image without an OpenAI key"}},"required":["id","name","revision","createdAt","updatedAt"]},"DefinitionLimits":{"type":"object","properties":{"ttlSeconds":{"type":["integer","null"],"description":"Agent lifetime: 60 to 31622400 seconds, or null to live until deleted. Default: until deleted for an agent made with an Idempotency-Key, 86400 for one made without"},"idleTtlSeconds":{"type":["integer","null"],"minimum":60,"maximum":31622400,"description":"Instead of ttlSeconds: the agent lives this long (60 to 31622400 seconds) from its latest run, so one in use is kept and one left idle expires. Not with ttlSeconds"}}},"OpenApi":{"type":"object","properties":{"name":{"type":"string","description":"Its operations reach the model as <name>__<operationId>: 1–32 letters and digits, single underscores between them"},"baseUrl":{"type":"string"},"allowTools":{"type":"array","items":{"type":"string"},"maxItems":1024,"description":"Only these operations (by operationId); at most 1024 in all"},"denyTools":{"type":"array","items":{"type":"string"},"maxItems":4096,"description":"None of these operations"},"exposure":{"type":"string","enum":["direct","codemode","both"],"description":"How the model calls its operations: directly, from js_exec (the default), or both"},"timeoutMs":{"type":"integer","minimum":1000,"maximum":1200000,"description":"Per call; default 30000"},"audience":{"type":"string","description":"With auth \"runtime\": the tokens' aud, when not baseUrl (behind a proxy, say): a URL on its origin, or a name that stays when the server moves, urn:camelrun:<tenant>:<name>"},"approval":{"type":"object","properties":{"default":{"type":"string","enum":["never","always","destructive"],"description":"never (the default), always, or destructive: tools annotated destructiveHint (MCP), operations other than GET, HEAD and OPTIONS (OpenAPI)"},"tools":{"type":"object","additionalProperties":{"type":"string","enum":["never","always"]},"description":"Per tool, by its own name: overrides the default"},"methods":{"type":"array","items":{"type":"string","enum":["GET","PUT","POST","DELETE","PATCH","HEAD","OPTIONS"]},"description":"Operations of these methods, unless named in tools"}},"additionalProperties":false,"description":"Which operations the user approves before each call. They are declared to the model directly; with auth \"runtime\", an approved call's identity token carries an approval claim"},"fileArguments":{"type":"string","enum":["on","off"],"description":"Whether the model may send the agent's files to its tools ({\"$file\": path}), and the runtime saves files they link to. Default on with auth \"runtime\", off otherwise: another party's server could be sent any file the agent can read"},"spec":{"type":"string","description":"The spec's URL; absent for a spec given inline"},"tools":{"type":"array","items":{"type":"string"},"description":"The operations the agent gets, by name"},"headerNames":{"type":"array","items":{"type":"string"}},"auth":{"$ref":"#/components/schemas/SourceAuth"}},"required":["name","baseUrl","tools"]},"DefinitionUpdated":{"allOf":[{"$ref":"#/components/schemas/Definition"},{"type":"object","properties":{"applied":{"type":"array","items":{"$ref":"#/components/schemas/ApplyResult"},"description":"With apply: \"all\", or applyOnUpdate on a save that made a new revision: one entry per live agent made from the definition"}}}]},"ApplyResult":{"type":"object","properties":{"agent":{"type":"string"},"requestId":{"type":"string","description":"The agent's configure request: poll GET /v1/agents/{agent}/requests/{requestId} for a queued one's outcome"},"status":{"type":"string","enum":["updated","queued","failed"],"description":"updated: the agent has the revision; queued: it takes it between its turns; failed: see error"},"error":{"type":"string"}},"required":["agent","requestId","status"]},"DefinitionInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"What its agents are for, in a sentence or two: shown to models as the description of each agent's MCP tool (/v1/agents/{id}/mcp)"},"model":{"type":"string","description":"A model id from GET /v1/models; the runtime default when omitted"},"systemPrompt":{"type":"string","minLength":1,"maxLength":32000},"thinkingLevel":{"type":"string","enum":["off","minimal","low","medium","high","xhigh","max"]},"maxOutputTokens":{"$ref":"#/components/schemas/MaxOutputTokens"},"temperature":{"$ref":"#/components/schemas/Temperature"},"fileTools":{"type":"boolean","description":"false: the model gets no file tools (read, write, edit, ls, glob, grep), only present_file; the mounts stay open to fs in js_exec, attachments and tool outputs. For applications with file tools of their own"},"codeMode":{"type":"boolean","description":"false: its agents get no js_exec and call every tool directly (AgentInput.codeMode)"},"limits":{"$ref":"#/components/schemas/DefinitionLimits"},"runLimits":{"allOf":[{"$ref":"#/components/schemas/RunLimits"},{"description":"The most one run may take, how long its model requests may go quiet, and how much context each carries. At maxResponses or maxSeconds, the turn ends before its next model request, after the tool calls of the response that reached it, with stopped \"turn_limit\" and code turn_limit; send another message to continue. Values above the runtime's maximums count as those. A model request that stalls (firstTokenSeconds, idleSeconds) is retried like other transient provider errors; when retries run out the run fails with code model_stream_stalled"}]},"mounts":{"type":"array","items":{"$ref":"#/components/schemas/MountInput"},"maxItems":16,"description":"Volumes for each agent's file tools, beside its own workspace at /workspace unless they include {workspace: false}"},"builtins":{"type":"array","items":{"$ref":"#/components/schemas/Builtin"},"maxItems":8,"description":"Tools the runtime answers itself: web_fetch reads a public page as text (rendering JavaScript-only pages through Firecrawl when a firecrawl key resolves); web_search searches the web through the first search provider with a key that answers (the tenant's own, else the platform's, which a prepaid tenant pays for per search at that provider's price); schedule lets the agent set, list and cancel its own wake-ups; ask_user lets the model ask the user questions, suspending its turn until they answer; generate_image makes or edits an image (OpenAI's gpt-image-2.5-flare on the tenant's OpenAI key, else the platform's, billed per token) and saves it to the workspace"},"webSearch":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"string","enum":["exa","brave","parallel"]},"minItems":1,"maxItems":3,"description":"The providers web_search tries, in order; each is skipped without a key, and the next is tried when one fails, times out or is rate limited","example":["brave"]}},"required":["providers"],"additionalProperties":false,"description":"Pin web_search to providers of your choosing instead of the runtime's order (exa, brave, parallel by default)"},"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/McpServerInput"},"maxItems":64,"description":"Remote MCP servers whose tools the runtime calls for the agent"},"openApi":{"type":"array","items":{"$ref":"#/components/schemas/OpenApiInput"},"maxItems":64,"description":"OpenAPI specs whose operations the runtime calls for the agent, as tools"},"delegate":{"allOf":[{"$ref":"#/components/schemas/DelegateSettings"},{"description":"With the delegate or agents builtin: who the model may hand tasks to, and how deep and wide. See the multi-agent guide"}]},"humanInput":{"type":"object","properties":{"expiresInSeconds":{"type":"integer","minimum":60,"maximum":2592000,"description":"How long an input waits for an answer: 7 days by default, at most 30, and never past the agent's own expiry"},"onExpire":{"type":"string","enum":["close","resume"],"description":"close (default): an expired input closes its call and the turn without the model; resume: the model is told and continues"},"approvers":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Who may answer any input besides the person whose message started the turn: actors, or channel senders like slack:U0123"}},"additionalProperties":false,"description":"Questions, approvals and setup steps the agent's turns wait on"},"applyOnUpdate":{"type":"boolean","description":"true: every save that makes a new revision (an upsert that changes it, or a PATCH) also applies it to every live agent made from the definition, as apply: \"all\" does, and answers with applied. Default false: only new agents get a new revision"}},"required":["name"]},"McpServerInput":{"type":"object","properties":{"name":{"type":"string","description":"Its tools reach the model as <name>__<tool>: 1–32 letters and digits, single underscores between them"},"url":{"type":"string","description":"The server's Streamable HTTP (or older SSE) endpoint; https, on a public address"},"allowTools":{"type":"array","items":{"type":"string"},"maxItems":512,"description":"Only these of its tools"},"denyTools":{"type":"array","items":{"type":"string"},"maxItems":512,"description":"None of these of its tools"},"exposure":{"type":"string","enum":["direct","codemode","both"],"description":"How the model calls its tools: directly, from js_exec (the default), or both"},"timeoutMs":{"type":"integer","minimum":1000,"maximum":1200000,"description":"How long a call may go without an answer; default 60000. Each progress notification the server sends restarts it, up to 1200000 in all"},"audience":{"type":"string","description":"With auth \"runtime\": the tokens' aud, when not the server's url (behind a proxy, say): a URL on its origin, or a name that stays when the server moves, urn:camelrun:<tenant>:<name>"},"approval":{"type":"object","properties":{"default":{"type":"string","enum":["never","always","destructive"],"description":"never (the default), always, or destructive: tools annotated destructiveHint (MCP), operations other than GET, HEAD and OPTIONS (OpenAPI)"},"tools":{"type":"object","additionalProperties":{"type":"string","enum":["never","always"]},"description":"Per tool, by its own name: overrides the default"}},"additionalProperties":false,"description":"Which tools the user approves before each call. Those tools are declared to the model directly; an approved call carries _meta[\"agent-runtime/approval\"] and an approval claim in its identity token"},"fileArguments":{"type":"string","enum":["on","off"],"description":"Whether the model may send the agent's files to its tools ({\"$file\": path}), and the runtime saves files they link to. Default on with auth \"runtime\", off otherwise: another party's server could be sent any file the agent can read"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Sent with every request to the server; stored encrypted and never returned. Leave out with auth to keep the ones stored for a server of this name and origin"},"auth":{"$ref":"#/components/schemas/SourceAuthInput"}},"required":["name","url"]},"SourceAuthInput":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["bearer"]},"token":{"type":"string"}},"required":["type","token"],"description":"A bearer token; stored encrypted and never returned"},{"type":"object","properties":{"type":{"type":"string","enum":["runtime"]}},"required":["type"],"description":"Each request carries a JWT the runtime signs (EdDSA, two minutes, audience the server's URL) naming the tenant, agent, subject, context and actor; verify it against /.well-known/jwks.json"}]},"OpenApiInput":{"type":"object","properties":{"name":{"type":"string","description":"Its operations reach the model as <name>__<operationId>: 1–32 letters and digits, single underscores between them"},"baseUrl":{"type":"string","description":"Where requests go; default the spec's first server. https, on a public address"},"allowTools":{"type":"array","items":{"type":"string"},"maxItems":1024,"description":"Only these operations (by operationId); at most 1024 in all"},"denyTools":{"type":"array","items":{"type":"string"},"maxItems":4096,"description":"None of these operations"},"exposure":{"type":"string","enum":["direct","codemode","both"],"description":"How the model calls its operations: directly, from js_exec (the default), or both"},"timeoutMs":{"type":"integer","minimum":1000,"maximum":1200000,"description":"Per call; default 30000"},"audience":{"type":"string","description":"With auth \"runtime\": the tokens' aud, when not baseUrl (behind a proxy, say): a URL on its origin, or a name that stays when the server moves, urn:camelrun:<tenant>:<name>"},"approval":{"type":"object","properties":{"default":{"type":"string","enum":["never","always","destructive"],"description":"never (the default), always, or destructive: tools annotated destructiveHint (MCP), operations other than GET, HEAD and OPTIONS (OpenAPI)"},"tools":{"type":"object","additionalProperties":{"type":"string","enum":["never","always"]},"description":"Per tool, by its own name: overrides the default"},"methods":{"type":"array","items":{"type":"string","enum":["GET","PUT","POST","DELETE","PATCH","HEAD","OPTIONS"]},"description":"Operations of these methods, unless named in tools"}},"additionalProperties":false,"description":"Which operations the user approves before each call. They are declared to the model directly; with auth \"runtime\", an approved call's identity token carries an approval claim"},"fileArguments":{"type":"string","enum":["on","off"],"description":"Whether the model may send the agent's files to its tools ({\"$file\": path}), and the runtime saves files they link to. Default on with auth \"runtime\", off otherwise: another party's server could be sent any file the agent can read"},"spec":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":{}}],"description":"The OpenAPI 3 document (JSON or YAML) as a URL, fetched each time the definition is saved, or the document itself. Leave out to keep a source's current operations"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Sent with every request to the API; stored encrypted and never returned. Leave out with auth to keep the ones stored for a source of this name and origin"},"auth":{"$ref":"#/components/schemas/SourceAuthInput"}},"required":["name"]},"DefinitionUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"minLength":1,"maxLength":1000,"description":"What its agents are for, in a sentence or two: shown to models as the description of each agent's MCP tool (/v1/agents/{id}/mcp)"},"model":{"type":["string","null"],"description":"A model id from GET /v1/models; the runtime default when omitted"},"systemPrompt":{"type":["string","null"],"minLength":1,"maxLength":32000},"thinkingLevel":{"type":["string","null"],"enum":["off","minimal","low","medium","high","xhigh","max",null]},"maxOutputTokens":{"allOf":[{"$ref":"#/components/schemas/MaxOutputTokens"},{"type":["integer","null"]}]},"temperature":{"allOf":[{"$ref":"#/components/schemas/Temperature"},{"type":["number","null"]}]},"fileTools":{"type":["boolean","null"],"description":"false: the model gets no file tools (read, write, edit, ls, glob, grep), only present_file; the mounts stay open to fs in js_exec, attachments and tool outputs. For applications with file tools of their own"},"codeMode":{"type":["boolean","null"],"description":"false: its agents get no js_exec and call every tool directly (AgentInput.codeMode)"},"limits":{"allOf":[{"$ref":"#/components/schemas/DefinitionLimits"},{"type":["object","null"]}]},"runLimits":{"allOf":[{"$ref":"#/components/schemas/RunLimits"},{"type":["object","null"],"description":"The most one run may take, how long its model requests may go quiet, and how much context each carries. At maxResponses or maxSeconds, the turn ends before its next model request, after the tool calls of the response that reached it, with stopped \"turn_limit\" and code turn_limit; send another message to continue. Values above the runtime's maximums count as those. A model request that stalls (firstTokenSeconds, idleSeconds) is retried like other transient provider errors; when retries run out the run fails with code model_stream_stalled"}]},"mounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/MountInput"},"maxItems":16,"description":"Volumes for each agent's file tools, beside its own workspace at /workspace unless they include {workspace: false}"},"builtins":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Builtin"},"maxItems":8,"description":"Tools the runtime answers itself: web_fetch reads a public page as text (rendering JavaScript-only pages through Firecrawl when a firecrawl key resolves); web_search searches the web through the first search provider with a key that answers (the tenant's own, else the platform's, which a prepaid tenant pays for per search at that provider's price); schedule lets the agent set, list and cancel its own wake-ups; ask_user lets the model ask the user questions, suspending its turn until they answer; generate_image makes or edits an image (OpenAI's gpt-image-2.5-flare on the tenant's OpenAI key, else the platform's, billed per token) and saves it to the workspace"},"webSearch":{"type":["object","null"],"properties":{"providers":{"type":"array","items":{"type":"string","enum":["exa","brave","parallel"]},"minItems":1,"maxItems":3,"description":"The providers web_search tries, in order; each is skipped without a key, and the next is tried when one fails, times out or is rate limited","example":["brave"]}},"required":["providers"],"additionalProperties":false,"description":"Pin web_search to providers of your choosing instead of the runtime's order (exa, brave, parallel by default)"},"mcpServers":{"type":["array","null"],"items":{"$ref":"#/components/schemas/McpServerInput"},"maxItems":64,"description":"Remote MCP servers whose tools the runtime calls for the agent"},"openApi":{"type":["array","null"],"items":{"$ref":"#/components/schemas/OpenApiInput"},"maxItems":64,"description":"OpenAPI specs whose operations the runtime calls for the agent, as tools"},"delegate":{"allOf":[{"$ref":"#/components/schemas/DelegateSettings"},{"type":["object","null"],"description":"With the delegate or agents builtin: who the model may hand tasks to, and how deep and wide. See the multi-agent guide"}]},"humanInput":{"type":["object","null"],"properties":{"expiresInSeconds":{"type":"integer","minimum":60,"maximum":2592000,"description":"How long an input waits for an answer: 7 days by default, at most 30, and never past the agent's own expiry"},"onExpire":{"type":"string","enum":["close","resume"],"description":"close (default): an expired input closes its call and the turn without the model; resume: the model is told and continues"},"approvers":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Who may answer any input besides the person whose message started the turn: actors, or channel senders like slack:U0123"}},"additionalProperties":false,"description":"Questions, approvals and setup steps the agent's turns wait on"},"applyOnUpdate":{"type":["boolean","null"],"description":"true: every save that makes a new revision (an upsert that changes it, or a PATCH) also applies it to every live agent made from the definition, as apply: \"all\" does, and answers with applied. Default false: only new agents get a new revision"},"revision":{"type":"integer","description":"Only update the definition if it is still at this revision"},"apply":{"type":"string","enum":["all"],"description":"Also reconfigure every live agent made from the definition to the new revision; each takes it between turns"}},"description":"Fields given replace the stored ones; null removes one"},"DefinitionAgent":{"type":"object","properties":{"id":{"type":"string"},"revision":{"type":"number"}},"required":["id","revision"]},"Run":{"type":"object","properties":{"id":{"type":"string","description":"run_…"},"status":{"type":"string","enum":["running","completed","input_required","failed"],"description":"running until it ends; then completed, failed, or input_required (a tool asked for approval or input, which a run cannot wait on: it ends there)"},"text":{"type":"string","description":"The final reply's text (\"\" while running, or when it said nothing)"},"output":{"description":"For a run with output: the answer, which fits its schema"},"error":{"$ref":"#/components/schemas/RunFailure"},"usage":{"type":["object","null"],"additionalProperties":{},"description":"What its model calls used: responses, input, output, cacheRead, cacheWrite, costUsd (and subagentCostUsd, what its sub-agents spent; imageCostUsd, what its generate_image calls spent)"},"servedModel":{"type":"string","description":"The model that made its last response (retries ask the same one), as provider/model-id; absent when it made none"},"toolCalls":{"type":"array","items":{"type":"object","additionalProperties":{}}},"toolErrors":{"type":"array","items":{"type":"object","additionalProperties":{}}},"sourceErrors":{"type":"array","items":{"type":"object","additionalProperties":{}}},"files":{"type":"array","items":{"type":"object","additionalProperties":{}}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"number"},"startedAt":{"type":"number","description":"When it began running"},"endedAt":{"type":"number"},"expiresAt":{"type":["number","null"],"description":"Once it ended: when its result, events and messages are deleted. null while it runs"},"resumes":{"type":"number","description":"Times it was resumed after the node running it was lost (at most 2)"},"handoffs":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["retire","drain"]},"at":{"type":"number"}},"required":["reason","at"]},"description":"Times a node leaving the cluster handed it to another at a step boundary, with nothing lost"}},"required":["id","status","text","error","usage","toolCalls","toolErrors","sourceErrors","files","expiresAt"]},"RunFailure":{"type":["object","null"],"properties":{"code":{"type":"string","description":"Stable: model_error, runtime_error, output_missing, spend_limit, turn_limit, aborted…"},"message":{"type":"string"},"uncertain":{"type":"boolean","description":"The runtime could not tell whether the run's work took effect"},"errorClass":{"type":"string","enum":["billing","rate_limit","server","refusal","auth","timeout","other"],"description":"What kind of failure: billing (the provider's 402, a quota or budget used up), rate_limit (429), server (5xx, overloaded, the provider unreachable), refusal (the model declined, or a safety filter stopped it), auth (401, 403, no key), timeout (the provider's, or the model stream went quiet), other. Values may be added: treat an unknown one as other"},"providerStatus":{"type":"integer","description":"The provider's HTTP status, when its error gives one"},"retryable":{"type":"boolean","description":"Whether the runtime retries such a failure itself (3 times, with backoff, on the same model). On a failed run: true means it was transient and its retries ran out, so trying again later, or another model, may work"},"model":{"type":"string","description":"The model that failed, as provider/model-id (an id of GET /v1/models)"}},"required":["code","message"],"description":"errorClass, providerStatus, retryable and model are there when a model call failed the run (model_error, model_stream_stalled, model_key_invalid…)"},"RunInput":{"type":"object","properties":{"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/RunInputPart"},"minItems":1}],"description":"What the run is asked: text, or parts (text and files, inline or by URL). Files are saved in a workspace volume the run gets for them; audio is transcribed for the model"},"definition":{"type":"string","description":"Take the configuration from this definition (its key or id; GET /v1/definitions): model, system prompt, thinking level, tool sources. Fields given here override it, as for an agent"},"model":{"type":"string","description":"A model id from GET /v1/models; the runtime default when omitted"},"systemPrompt":{"type":"string"},"systemPromptAppend":{"type":"string","maxLength":32000},"thinkingLevel":{"type":"string","enum":["off","minimal","low","medium","high","xhigh","max"]},"maxOutputTokens":{"$ref":"#/components/schemas/MaxOutputTokens"},"temperature":{"$ref":"#/components/schemas/Temperature"},"builtins":{"type":"array","items":{"type":"string","enum":["web_fetch","web_search","delegate","generate_image"]},"maxItems":8,"description":"Tools the runtime answers itself (generate_image gives the run a workspace for its images). Not schedule or ask_user: a run has no later and no one to ask"},"delegate":{"allOf":[{"$ref":"#/components/schemas/DelegateSettings"},{"description":"With the delegate or agents builtin: who the model may hand tasks to, and how deep and wide. See the multi-agent guide"}]},"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/InlineMcpServerInput"},"maxItems":64,"description":"Remote MCP servers whose tools the run may call, as an agent's own: no credentials (auth \"runtime\" or none). A server that cannot be listed shows in sourceErrors"},"fileTools":{"type":"boolean","description":"true: the run gets a workspace volume and file tools. Default: none, unless input has files"},"codeMode":{"type":"boolean","description":"true: the model gets js_exec. Default: true when the run has tools (builtins, MCP servers, a definition, files), false for a tool-less run, whose model then sees only your instructions"},"mounts":{"type":"array","items":{"$ref":"#/components/schemas/Mount"},"description":"Existing volumes for the run's file tools"},"output":{"type":"object","properties":{"schema":{"type":"object","additionalProperties":{},"description":"A JSON Schema for an object (type: \"object\"; at most 64 KB)","example":{"type":"object","properties":{"sentiment":{"type":"string","enum":["positive","neutral","negative"]}},"required":["sentiment"]}}},"required":["schema"],"additionalProperties":false,"description":"Structured output: the agent ends this run by calling a final_output tool whose arguments are the schema, checked against it (a call that does not fit goes back to the model with what is wrong). The run's outcome.result.output is that object. A model that answers in text instead is asked once more, with a reminder; a run that still ends without an output fails with code output_missing. The tool stays declared until a prompt without output. Not with whileRunning: steer"},"keyScope":{"type":"string"},"modelHeaders":{"$ref":"#/components/schemas/ModelHeaders"},"spendLimit":{"allOf":[{"$ref":"#/components/schemas/SpendLimitInput"},{"description":"The run's budget in USD: it ends before its next model request once it has spent this"}]},"runLimits":{"allOf":[{"$ref":"#/components/schemas/RunLimits"},{"description":"The most one run may take, how long its model requests may go quiet, and how much context each carries. At maxResponses or maxSeconds, the turn ends before its next model request, after the tool calls of the response that reached it, with stopped \"turn_limit\" and code turn_limit; send another message to continue. Values above the runtime's maximums count as those. A model request that stalls (firstTokenSeconds, idleSeconds) is retried like other transient provider errors; when retries run out the run fails with code model_stream_stalled"}]},"subject":{"type":"string","description":"Who the run acts for (a user id in your app): `sub` in its tool servers' identity tokens"},"context":{"type":"object","additionalProperties":{},"description":"Claims your tool servers need, as `ctx` in its identity tokens; at most 4 KB"},"actor":{"type":"string","description":"Who is acting in this turn (a user id in your app): `act` in its tools' identity tokens"},"from":{"type":"object","properties":{"id":{"type":"string","description":"The sender's id in your app; the model may rely on it"},"name":{"type":"string","description":"Display name, chosen by the sender"},"username":{"type":"string","description":"Handle, chosen by the sender"}},"required":["id"],"additionalProperties":false,"description":"Who sent this message. The model sees it in a block only the runtime can write; `from.id` is also the turn's actor unless `actor` is given"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value data about this message (its source, a client-side id): at most 16 keys of 1–64 characters, values of at most 512. Kept on the user message (history, events, snapshots) and the request, and sent with its run's webhook events; never shown to the model","example":{"source":"web","clientMessageId":"m_123"}},"name":{"type":"string","description":"A name for the run, in its traces"},"wait":{"anyOf":[{"type":"boolean"},{"type":"number","minimum":0}],"description":"Wait for the run to end before answering: true for up to 60 seconds, or a number of seconds (at most 60). It answers 200 with the ended run, or 202 with it still running when the wait ends. Default: answer at once, 202. ?wait=<seconds> does the same"},"retentionSeconds":{"type":"integer","minimum":60,"maximum":604800,"description":"How long the run's result, events and messages are kept once it ends, before they are deleted: 60 to 604800 seconds. Default: the runtime's (86400)"}},"required":["input"],"additionalProperties":false},"RunInputPart":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["file"]},"name":{"type":"string"},"data":{"type":"string","description":"The file's bytes, base64: at most 4 MiB across a run's inline files"},"contentType":{"type":"string"},"transcribe":{"type":"boolean","description":"Whether this file is transcribed for the model (audio only): default true for audio (an audio/* content type), false for anything else. See the voice and audio guide"}},"required":["type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["file"]},"url":{"type":"string","description":"An https URL the runtime fetches the file from (public addresses only; at most 64 MiB)"},"name":{"type":"string"},"contentType":{"type":"string"},"transcribe":{"type":"boolean","description":"Whether this file is transcribed for the model (audio only): default true for audio (an audio/* content type), false for anything else. See the voice and audio guide"}},"required":["type","url"],"additionalProperties":false}]},"MountsInput":{"type":"object","properties":{"mounts":{"type":"array","items":{"$ref":"#/components/schemas/MountInput"}}},"required":["mounts"]},"VolumeSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"number"}},"required":["id","name","createdAt"]},"Volume":{"allOf":[{"$ref":"#/components/schemas/VolumeSummary"},{"type":"object","properties":{"seq":{"type":"number","description":"Increases with every change to the volume"},"files":{"type":"number"},"bytes":{"type":"number"},"origin":{"type":"object","properties":{"volume":{"type":"string"},"snapshot":{"type":"string"},"seq":{"type":"number"}},"required":["volume","seq"],"description":"What a fork was copied from"}},"required":["seq","files","bytes"]}]},"VolumeInput":{"type":"object","properties":{"name":{"type":"string"},"key":{"type":"string","description":"Your name for the volume (1–200 letters, digits and ._:-): the first create with a key makes it, every later one answers with it (existing: true), for as long as it lives. A deleted one's key makes no other"}}},"Snapshot":{"type":"object","properties":{"id":{"type":"string"},"volume":{"type":"string"},"name":{"type":"string"},"seq":{"type":"number"},"createdAt":{"type":"number"},"files":{"type":"number"},"bytes":{"type":"number"},"pinned":{"type":"boolean","description":"Kept until unpinned: publish's pruning passes it by, it counts against 10,000 pinned snapshots rather than the 100 others, and deleting it takes unpinning or force"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own labels, e.g. {\"release\": \"v12\"}: at most 16, keys of 1–64 characters, values of at most 256"}},"required":["id","volume","name","seq","createdAt","files","bytes","pinned","labels"]},"SnapshotMade":{"allOf":[{"$ref":"#/components/schemas/Snapshot"},{"type":"object","properties":{"contents":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"number"},"sha256":{"type":"string","description":"Hex"}},"required":["path","size","sha256"]},"description":"A snapshot made from contents: each file as stored, to check against what was sent"}}}]},"SnapshotInput":{"type":"object","properties":{"name":{"type":"string","description":"1–120 characters; default seq <n>"},"pinned":{"type":"boolean"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own labels, e.g. {\"release\": \"v12\"}: at most 16, keys of 1–64 characters, values of at most 256"},"files":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","properties":{"data":{"type":"string","description":"Base64"},"contentType":{"type":"string"}},"required":["data"]}]},"description":"A snapshot of these files (path to text, or {data} in base64) instead of the volume: the volume and its seq are untouched. At most 1,000 files and 16 MiB. For bringing in versions kept elsewhere"}}},"SnapshotUpdate":{"type":"object","properties":{"pinned":{"type":"boolean"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Replaces its labels"}}},"Restored":{"type":"object","properties":{"snapshot":{"type":"string"},"seq":{"type":"number","description":"The volume's seq after the restore"},"written":{"type":"number","description":"Files written back as the snapshot had them"},"removed":{"type":"number","description":"Files the snapshot did not have, removed"}},"required":["snapshot","seq","written","removed"]},"RestoreInput":{"type":"object","properties":{"snapshot":{"type":"string","description":"The snapshot (snap_…) to make the volume as"}},"required":["snapshot"],"additionalProperties":false},"ForkInput":{"type":"object","properties":{"name":{"type":"string"},"snapshot":{"type":"string","description":"Fork this snapshot instead of the current state"}}},"Link":{"type":"object","properties":{"url":{"type":"string","description":"Send the method to it, with no Authorization header"},"urlPath":{"type":"string","description":"The url's path on the runtime: for a proxy that serves the link at its own origin, in front of a runtime browsers cannot reach"},"method":{"type":"string","enum":["GET","PUT"]},"tenant":{"type":"string"},"volume":{"type":"string"},"path":{"type":"string"},"expiresAt":{"type":"number"},"maxBytes":{"type":"number"},"contentType":{"type":"string"}},"required":["url","urlPath","method","tenant","volume","path","expiresAt"]},"LinkInput":{"type":"object","properties":{"path":{"type":"string","description":"The file's path in the volume"},"method":{"type":"string","enum":["GET","PUT"],"description":"GET (default) downloads the file; PUT uploads it, creating or replacing it"},"expiresIn":{"type":"integer","description":"Seconds the link works: 900 by default, at most 86400"},"maxBytes":{"type":"integer","description":"PUT: the largest upload it takes (default and at most 256 MiB)"},"contentType":{"type":"string","description":"PUT: the upload's content type; an upload declaring another is refused"}},"required":["path"]},"Changes":{"type":"object","properties":{"seq":{"type":"number"},"changes":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"number"},"path":{"type":"string"},"kind":{"type":"string","enum":["write","delete"]},"version":{"type":"number"},"size":{"type":"number"},"by":{"type":"string"},"at":{"type":"number"}},"required":["seq","path","kind","at"]}},"gap":{"type":"boolean","description":"Older changes are no longer kept; list the files instead"}},"required":["seq","changes"]},"FileList":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/VolumeFile"}},"next":{"type":"string","description":"Pass as `after` for the next page"}},"required":["files"]},"FileContents":{"type":"object","properties":{"seq":{"type":"number","description":"The volume's change number the files were read at (the snapshot's, for a snapshot)"},"snapshot":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"number"},"version":{"type":"number"},"contentType":{"type":"string"},"sha256":{"type":"string","description":"Of the file's bytes, hex"},"text":{"type":"string","description":"The contents, for a file that is UTF-8 text"},"data":{"type":"string","description":"The contents base64, for any other file"}},"required":["path","size","version","contentType","sha256"]}}},"required":["seq","files"]}},"parameters":{}},"paths":{"/v1/links/{token}/{name}":{"get":{"security":[],"parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"},{"schema":{"type":"string","description":"The file's name, for browsers; not checked"},"required":true,"description":"The file's name, for browsers; not checked","name":"name","in":"path"}],"responses":{"200":{"description":"The file, with safe download headers","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"The requested range","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"security":[],"parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"},{"schema":{"type":"string","description":"The file's name, for browsers; not checked"},"required":true,"description":"The file's name, for browsers; not checked","name":"name","in":"path"}],"requestBody":{"description":"The file's bytes, streamed; at most the link's maxBytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"The file's new version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeFile"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/files/{token}/{name}":{"get":{"security":[],"parameters":[{"schema":{"type":"string"},"required":true,"name":"token","in":"path"},{"schema":{"type":"string","description":"The file's name, for tools and browsers; not checked"},"required":true,"description":"The file's name, for tools and browsers; not checked","name":"name","in":"path"},{"schema":{"type":"string","description":"bytes=start-end (a file's URL)"},"required":false,"description":"bytes=start-end (a file's URL)","name":"range","in":"header"}],"responses":{"200":{"description":"The file; a directory's manifest (JSON: snapshot, root, files with their own URLs, and archive); or its archive (tar.gz)","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/FileManifest"}}}},"206":{"description":"The requested range","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"410":{"description":"The file changed since the call, or the call's files are no longer kept","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/alerts/confirmation/inspect":{"post":{"security":[],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","maxLength":100}},"required":["token"]}}}},"responses":{"200":{"description":"Mailbox confirmation state","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["unavailable"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["ready","confirmed"]},"tenant":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["status","tenant","email"]}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/alerts/confirmation/confirm":{"post":{"security":[],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","maxLength":100}},"required":["token"]}}}},"responses":{"200":{"description":"Mailbox confirmation state","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["unavailable"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["ready","confirmed"]},"tenant":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["status","tenant","email"]}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/alerts/unsubscribe/inspect":{"post":{"security":[],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","maxLength":100}},"required":["token"]}}}},"responses":{"200":{"description":"Email opt-out state","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["unavailable"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["ready","unsubscribed"]},"tenant":{"type":"string"},"email":{"type":"string"}},"required":["status","tenant","email"]}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/alerts/unsubscribe/stop":{"post":{"security":[],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","maxLength":100}},"required":["token"]}}}},"responses":{"200":{"description":"Email opt-out state","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["unavailable"]}},"required":["status"]},{"type":"object","properties":{"status":{"type":"string","enum":["ready","unsubscribed"]},"tenant":{"type":"string"},"email":{"type":"string"}},"required":["status","tenant","email"]}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me":{"get":{"responses":{"200":{"description":"The caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/providers":{"get":{"responses":{"200":{"description":"Key status per provider, and the tenant's own providers","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Provider"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/providers/{name}":{"put":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomProviderInput"}}}},"responses":{"200":{"description":"The provider, never its key or header values; agents name its models <name>/<model id>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Provider"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"The provider is deleted: agents on its models fail at their next call until it is set again","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/providers/{provider}/key":{"put":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"provider","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyInput"}}}},"responses":{"200":{"description":"The key is stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeySet"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"provider","in":"path"}],"responses":{"200":{"description":"The key is deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/key-scopes/{scope}/providers/{provider}":{"put":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"scope","in":"path"},{"schema":{"type":"string"},"required":true,"name":"provider","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyScopeEntryInput"}}}},"responses":{"200":{"description":"The entry is stored; agents in the scope use it from their next model call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyScope"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"scope","in":"path"},{"schema":{"type":"string"},"required":true,"name":"provider","in":"path"}],"responses":{"200":{"description":"The entry is deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/key-scopes/{scope}/model-providers/{name}":{"put":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"scope","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomProviderInput"}}}},"responses":{"200":{"description":"The provider, never its key or header values; the scope's agents name its models <name>/<model id>","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Provider"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"scope","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"responses":{"200":{"description":"The provider is deleted: the scope's agents on its models call the tenant's of that name, if any, or fail","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/key-scopes/{scope}/model-providers":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"scope","in":"path"}],"responses":{"200":{"description":"The scope's own model providers, never their key or header values","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Provider"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/key-scopes/{scope}":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"scope","in":"path"}],"responses":{"200":{"description":"The providers the scope has entries for, never their secrets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyScope"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"scope","in":"path"}],"responses":{"200":{"description":"Every entry and model provider of the scope is deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointInput"}}}},"responses":{"201":{"description":"The endpoint, with its signing secret, shown only now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreated"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"responses":{"200":{"description":"The tenant's webhook endpoints","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhookId}":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhookId","in":"path"}],"responses":{"200":{"description":"The endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhookId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointUpdate"}}}},"responses":{"200":{"description":"The endpoint; what the request left out is unchanged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhookId","in":"path"}],"responses":{"200":{"description":"The endpoint and its undelivered events are removed","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhookId}/secret":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhookId","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"A new signing secret, shown only now; the old one also signs for 24 hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecret"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/telemetry":{"put":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryInput"}}}},"responses":{"200":{"description":"Where the tenant's traces go now; header values are never returned. Fields left out keep their current values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Telemetry"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"responses":{"200":{"description":"Where the tenant's traces go, with header names only, and how the last export went","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Telemetry"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"responses":{"200":{"description":"Traces are no longer exported","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/telemetry/test":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"One test span, sent now: what the endpoint answered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryTest"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage-webhook":{"put":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageWebhookInput"}}}},"responses":{"200":{"description":"The receiver; with its signing secret the first time only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageWebhookSet"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"responses":{"200":{"description":"The receiver","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageWebhook"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"responses":{"200":{"description":"The receiver and its undelivered events are removed","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage-webhook/secret":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"A new signing secret, shown only now; the old one also signs for 24 hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecret"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/models":{"get":{"parameters":[{"schema":{"type":"string"},"required":false,"name":"provider","in":"query"},{"schema":{"type":"string","enum":["true"],"description":"Only models this tenant has a key for. An empty list comes with an X-Camelrun-Hint header saying which key to set"},"required":false,"description":"Only models this tenant has a key for. An empty list comes with an X-Camelrun-Hint header saying which key to set","name":"available","in":"query"},{"schema":{"type":"string","description":"Include this key scope's own providers' models, as its agents see them"},"required":false,"description":"Include this key scope's own providers' models, as its agents see them","name":"keyScope","in":"query"}],"responses":{"200":{"description":"Models in the catalog","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents":{"get":{"responses":{"200":{"description":"The tenant's agents","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentSummary"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"parameters":[{"schema":{"type":"string","description":"Provisioning with the same key returns the same agent"},"required":false,"description":"Provisioning with the same key returns the same agent","name":"idempotency-key","in":"header"},{"schema":{"type":"string","description":"W3C trace context (00-<trace-id>-<span-id>-<flags>): the run's spans continue this trace","example":"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"},"required":false,"description":"W3C trace context (00-<trace-id>-<span-id>-<flags>): the run's spans continue this trace","name":"traceparent","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentInput"}}}},"responses":{"201":{"description":"The agent and its scoped token","headers":{"X-RateLimit-Limit":{"description":"Agents the tenant may make a minute","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"What is left of it this minute","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window resets: windows align to the clock minute (UTC)","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreated"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true"],"description":"Include each tool's input schema in toolSources"},"required":false,"description":"Include each tool's input schema in toolSources","name":"schemas","in":"query"},{"schema":{"type":"string","enum":["true"],"description":"List every MCP server now, connecting to it, rather than showing what was last listed. A running agent takes changes at its next start or reconfiguration"},"required":false,"description":"List every MCP server now, connecting to it, rather than showing what was last listed. A running agent takes changes at its next start or reconfiguration","name":"refresh","in":"query"}],"responses":{"200":{"description":"The agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDetail"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The agent is deleted: it stops at once, and its stored data is purged shortly after","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/credentials":{"get":{"parameters":[{"schema":{"type":"string","description":"The agent's id, or the key it was made with (Idempotency-Key, the SDKs' upsert key)"},"required":true,"description":"The agent's id, or the key it was made with (Idempotency-Key, the SDKs' upsert key)","name":"id","in":"path"}],"responses":{"200":{"description":"An existing agent's id and scoped token, its configuration untouched (the SDKs' agents.get). 404 when no live agent has this id or key; 409 AGENT_KEYLESS for one made without a key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCredentials"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/credentials/rotate":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"A new token for the agent: the old one stops working at once, and connections made with it close. The application serving the agent reconnects with this one; credentials gives it from now on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCredentials"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/fork":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"The fork's key, when the body gives none"},"required":false,"description":"The fork's key, when the body gives none","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentForkInput"}}}},"responses":{"201":{"description":"A new agent with the source's configuration, a copy of its history to the fork point, and a fork of its workspace","headers":{"X-RateLimit-Limit":{"description":"Agents the tenant may make a minute","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"What is left of it this minute","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window resets: windows align to the clock minute (UTC)","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentForked"}}}},"409":{"description":"FORK_POINT_RUNNING: atMessage is in a turn that has not ended; or the key names another agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/events":{"get":{"security":[{"bearer":[]},{"console":[]},{"browser":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["1"],"description":"Answer once, as JSON, instead of streaming"},"required":false,"description":"Answer once, as JSON, instead of streaming","name":"poll","in":"query"},{"schema":{"type":"string","description":"With poll: seconds (at most 25) to wait for the next event when none is buffered"},"required":false,"description":"With poll: seconds (at most 25) to wait for the next event when none is buffered","name":"wait","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"By default, where the stream cannot replay (no Last-Event-ID, or one behind the buffer), it starts with a snapshot of the running turn instead of what is buffered or a 409. Each message_update is its delta alone, so a subscriber folds from the snapshot. 0: no snapshot; behind the buffer is a 409"},"required":false,"description":"By default, where the stream cannot replay (no Last-Event-ID, or one behind the buffer), it starts with a snapshot of the running turn instead of what is buffered or a 409. Each message_update is its delta alone, so a subscriber folds from the snapshot. 0: no snapshot; behind the buffer is a 409","name":"snapshot","in":"query"},{"schema":{"type":"string","enum":["1"],"description":"Also send the agent's children's progress, from its delegate and spawn_agent calls: subagent_start, subagent_event (a child's event, streamed text left out) and subagent_end (a background child's, as its notification lands; both with background: true). Without it, none of them"},"required":false,"description":"Also send the agent's children's progress, from its delegate and spawn_agent calls: subagent_start, subagent_event (a child's event, streamed text left out) and subagent_end (a background child's, as its notification lands; both with background: true). Without it, none of them","name":"subagents","in":"query"},{"schema":{"type":"string","description":"Only this request's events and response (a run's id, a prompt's requestId), besides snapshots"},"required":false,"description":"Only this request's events and response (a run's id, a prompt's requestId), besides snapshots","name":"request","in":"query"},{"schema":{"type":"string","description":"Resume after this event id; absent or 0 takes everything buffered. Behind the buffer: 409"},"required":false,"description":"Resume after this event id; absent or 0 takes everything buffered. Behind the buffer: 409","name":"last-event-id","in":"header"}],"responses":{"200":{"description":"Server-sent events, each `id: <cursor>` and `data: <ClientEvent>`, after a `ready` frame; with poll=1, the events as JSON","content":{"text/event-stream":{"schema":{"type":"string"}},"application/json":{"schema":{"$ref":"#/components/schemas/EventPoll"}}}},"409":{"description":"REPLAY_GAP: the events after Last-Event-ID are gone; read state and history, then stream from state's cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The agent has too many subscribers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/state":{"get":{"security":[{"bearer":[]},{"console":[]},{"browser":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Request state and the stream's cursor; for a browser token, each request only as how it ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionState"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/history":{"get":{"security":[{"bearer":[]},{"console":[]},{"browser":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Page the history: at least this many messages (1 to 500, default 50) in whole turns, where there are that many. Without limit or before, the whole transcript"},"required":false,"description":"Page the history: at least this many messages (1 to 500, default 50) in whole turns, where there are that many. Without limit or before, the whole transcript","name":"limit","in":"query"},{"schema":{"type":"string","description":"The page ends before this message index: a page's next"},"required":false,"description":"The page ends before this message index: a page's next","name":"before","in":"query"}],"responses":{"200":{"description":"With limit or before, a page of whole turns (HistoryPage); otherwise the whole transcript (History)","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/HistoryPage"},{"$ref":"#/components/schemas/History"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/browser-tokens":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrowserTokenInput"}}}},"responses":{"201":{"description":"A token a browser reads this agent with, until it expires","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrowserToken"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/abort":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AbortInput"}}}},"responses":{"200":{"description":"The agent is stopped: its running turn is aborted, the runs queued behind it are cancelled (unless queued: \"keep\"), and its running background sub-agents are aborted (unless children: \"keep\"). On a sub-agent, it stops that one alone, and its parent's notification follows with status aborted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Aborted"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/prompt":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"W3C trace context (00-<trace-id>-<span-id>-<flags>): the run's spans continue this trace","example":"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"},"required":false,"description":"W3C trace context (00-<trace-id>-<span-id>-<flags>): the run's spans continue this trace","name":"traceparent","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptInput"}}}},"responses":{"202":{"description":"The accepted request","headers":{"X-RateLimit-Limit":{"description":"Runs the tenant may make a minute","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"What is left of it this minute","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window resets: windows align to the clock minute (UTC)","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestRecord"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/uploads/{requestId}/{name}":{"put":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"requestId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"name","in":"path"}],"requestBody":{"description":"The file's bytes, streamed","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"The saved file, in the agent's workspace under uploads/<requestId>/; attach it to that request as {path}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Upload"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/configuration":{"patch":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureInput"}}}},"responses":{"202":{"description":"Configuration accepted; poll its request for completion. Conversation history is preserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestRecord"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/requests/{requestId}":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"requestId","in":"path"},{"schema":{"type":"string","description":"Seconds (at most 25) to wait for a running request to settle: it answers as soon as it does, else when the wait ends, still running. Default 0"},"required":false,"description":"Seconds (at most 25) to wait for a running request to settle: it answers as soon as it does, else when the wait ends, still running. Default 0","name":"wait","in":"query"}],"responses":{"200":{"description":"The request and, once settled, its outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestRecord"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/inputs":{"get":{"security":[{"bearer":[]},{"console":[]},{"browser":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["pending","answered","declined","cancelled","expired","superseded"]},"required":false,"name":"state","in":"query"}],"responses":{"200":{"description":"The agent's human inputs, newest first","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Input"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerInputs"}}}},"responses":{"200":{"description":"The same answers were recorded before","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnsweredAll"}}}},"202":{"description":"Every answer is recorded, or none is","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnsweredAll"}}}},"409":{"description":"An input had already settled otherwise","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/inputs/{inputId}":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"inputId","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerInput"}}}},"responses":{"200":{"description":"The same answer was recorded before","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answered"}}}},"202":{"description":"The answer is recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answered"}}}},"409":{"description":"The input had already settled otherwise","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inputs":{"get":{"parameters":[{"schema":{"type":"string","enum":["pending","answered","declined","cancelled","expired","superseded"]},"required":false,"name":"state","in":"query"}],"responses":{"200":{"description":"The tenant's human inputs across its agents, newest first: what waits on someone","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Input"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/schedules":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The agent's schedules","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Schedule"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleInput"}}}},"responses":{"201":{"description":"The schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Schedule"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/schedules/{scheduleId}":{"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"scheduleId","in":"path"}],"responses":{"200":{"description":"The schedule is deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tokens":{"get":{"responses":{"200":{"description":"The tenant's API tokens","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Token"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenInput"}}}},"responses":{"201":{"description":"The token, with its secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenCreated"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions":{"delete":{"responses":{"200":{"description":"Signed out everywhere: every console session of the account ends now, this one too","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedOut"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/oauth/grants":{"get":{"responses":{"200":{"description":"The applications the tenant let act for it over OAuth (the hosted MCP endpoint's clients)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OAuthGrant"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/oauth/grants/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The grant is revoked: its tokens stop working at once. Webhooks and a trace export it set (before grants could no longer set them) keep sending, and are listed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Revoked"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tokens/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The token is revoked. Webhooks and a trace export it set keep sending, and are listed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Revoked"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"parameters":[{"schema":{"type":"string","description":"1–365, default 30"},"required":false,"description":"1–365, default 30","name":"days","in":"query"}],"responses":{"200":{"description":"Token usage per UTC day and model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transcriptions":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionInput"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/TranscriptionForm"}}}},"responses":{"200":{"description":"The audio's transcript","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcription"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/images":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageInput"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImageForm"}}}},"responses":{"200":{"description":"The images made: base64, or where they were saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Images"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing":{"get":{"responses":{"200":{"description":"Prepaid credit: balance, this month, recent entries and rates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Billing"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/alerts":{"get":{"responses":{"200":{"description":"Billing alert settings","content":{"application/json":{"schema":{"type":"object","properties":{"threshold":{"type":"integer","description":"Low-balance threshold, in micro-USD (1 USD = 1000000)"},"emailEnabled":{"type":"boolean"},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["pending","verified","bounced","unsubscribed"]},"events":{"type":"object","properties":{"low":{"type":"boolean"},"depleted":{"type":"boolean"},"problems":{"type":"boolean"},"receipts":{"type":"boolean"}},"required":["low","depleted","problems","receipts"]}},"required":["id","email","status","events"]}}},"required":["threshold","emailEnabled","recipients"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"thresholdUsd":{"type":"number","minimum":0.01,"maximum":500}},"required":["thresholdUsd"]}}}},"responses":{"200":{"description":"Billing alert settings","content":{"application/json":{"schema":{"type":"object","properties":{"threshold":{"type":"integer","description":"Low-balance threshold, in micro-USD (1 USD = 1000000)"},"emailEnabled":{"type":"boolean"},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["pending","verified","bounced","unsubscribed"]},"events":{"type":"object","properties":{"low":{"type":"boolean"},"depleted":{"type":"boolean"},"problems":{"type":"boolean"},"receipts":{"type":"boolean"}},"required":["low","depleted","problems","receipts"]}},"required":["id","email","status","events"]}}},"required":["threshold","emailEnabled","recipients"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/alerts/recipients":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email"},"events":{"type":"object","properties":{"low":{"type":"boolean"},"depleted":{"type":"boolean"},"problems":{"type":"boolean"},"receipts":{"type":"boolean"}},"required":["low","depleted","problems","receipts"]}},"required":["email"]}}}},"responses":{"201":{"description":"Address awaiting mailbox confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["pending","verified","bounced","unsubscribed"]},"events":{"type":"object","properties":{"low":{"type":"boolean"},"depleted":{"type":"boolean"},"problems":{"type":"boolean"},"receipts":{"type":"boolean"}},"required":["low","depleted","problems","receipts"]}},"required":["id","email","status","events"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/alerts/recipients/{id}":{"put":{"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"low":{"type":"boolean"},"depleted":{"type":"boolean"},"problems":{"type":"boolean"},"receipts":{"type":"boolean"}},"required":["low","depleted","problems","receipts"]}}}},"responses":{"200":{"description":"Recipient preferences","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["pending","verified","bounced","unsubscribed"]},"events":{"type":"object","properties":{"low":{"type":"boolean"},"depleted":{"type":"boolean"},"problems":{"type":"boolean"},"receipts":{"type":"boolean"}},"required":["low","depleted","problems","receipts"]}},"required":["id","email","status","events"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Recipient removed","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/alerts/recipients/{id}/resend":{"post":{"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Confirmation queued","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"boolean","enum":[true]}},"required":["queued"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/ledger":{"get":{"parameters":[{"schema":{"type":"string","description":"Entries older than this id"},"required":false,"description":"Entries older than this id","name":"before","in":"query"},{"schema":{"type":"string","description":"1–200, default 50"},"required":false,"description":"1–200, default 50","name":"limit","in":"query"}],"responses":{"200":{"description":"The credit ledger, newest first, a page at a time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ledger"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/checkout":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutInput"}}}},"responses":{"201":{"description":"A Stripe Checkout session; the credit is added once Stripe reports the payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/card-check":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"responses":{"201":{"description":"A Stripe Checkout session that verifies a card, with no charge, to unlock starting credit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCheck"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/card-check/confirm":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCheckConfirmInput"}}}},"responses":{"200":{"description":"The card check's outcome, settled now if Stripe's webhook has not arrived yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCheckOutcome"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/payment-method":{"get":{"responses":{"200":{"description":"Saved card display details from Stripe","content":{"application/json":{"schema":{"type":"object","properties":{"portal":{"type":"boolean"},"customer":{"type":"boolean"},"card":{"type":["object","null"],"properties":{"brand":{"type":"string"},"last4":{"type":"string"},"expMonth":{"type":"number"},"expYear":{"type":"number"}},"required":["brand","last4","expMonth","expYear"]}},"required":["portal","customer","card"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/portal":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"flow":{"type":"string","enum":["manage","payment_method"],"default":"manage"},"resumeAutoTopup":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"201":{"description":"Stripe-hosted billing portal","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/auto-topup":{"get":{"responses":{"200":{"description":"Auto top-up state","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"state":{"type":"string","enum":["off","on","processing","cancelling","action_required","paused_declined","paused_no_card","paused_expired","limit_reached","reconcile"]},"version":{"type":"number"},"threshold":{"type":"number"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"monthlyLimit":{"type":"number"},"usedThisPeriod":{"type":"number"},"held":{"type":"number"},"resetsAt":{"type":"number"},"attempt":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"card":{"type":["object","null"],"properties":{"brand":{"type":"string"},"last4":{"type":"string"},"expMonth":{"type":"number"},"expYear":{"type":"number"}},"required":["brand","last4","expMonth","expYear"]},"invoiceUrl":{"type":["string","null"]},"canRetry":{"type":"boolean"},"submitted":{"type":"boolean"}},"required":["id","state","amount","fee","total","card","invoiceUrl","canRetry","submitted"]}},"required":["enabled","state","version","threshold","amount","fee","total","monthlyLimit","usedThisPeriod","held","resetsAt","attempt"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/auto-topup/quote":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"thresholdUsd":{"type":"number"},"amountUsd":{"type":"number"},"monthlyLimitUsd":{"type":"number"}},"required":["thresholdUsd","amountUsd","monthlyLimitUsd"],"additionalProperties":false}}}},"responses":{"201":{"description":"Exact terms for confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string"},"threshold":{"type":"number"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"monthlyLimit":{"type":"number"},"card":{"type":["object","null"],"properties":{"brand":{"type":"string"},"last4":{"type":"string"},"expMonth":{"type":"number"},"expYear":{"type":"number"}},"required":["brand","last4","expMonth","expYear"]},"immediate":{"type":"boolean"},"expiresAt":{"type":"number"}},"required":["id","version","threshold","amount","fee","total","monthlyLimit","card","immediate","expiresAt"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"id","in":"query"}],"responses":{"200":{"description":"Saved draft with current confirmation version","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"string"},"threshold":{"type":"number"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"monthlyLimit":{"type":"number"},"card":{"type":["object","null"],"properties":{"brand":{"type":"string"},"last4":{"type":"string"},"expMonth":{"type":"number"},"expYear":{"type":"number"}},"required":["brand","last4","expMonth","expYear"]},"immediate":{"type":"boolean"},"expiresAt":{"type":"number"}},"required":["id","version","threshold","amount","fee","total","monthlyLimit","card","immediate","expiresAt"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/auto-topup/enable":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string","format":"uuid"},"version":{"type":"string","minLength":64,"maxLength":64},"consent":{"type":"boolean","enum":[true]}},"required":["quoteId","version","consent"],"additionalProperties":false}}}},"responses":{"200":{"description":"Auto top-up enabled","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"state":{"type":"string","enum":["off","on","processing","cancelling","action_required","paused_declined","paused_no_card","paused_expired","limit_reached","reconcile"]},"version":{"type":"number"},"threshold":{"type":"number"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"monthlyLimit":{"type":"number"},"usedThisPeriod":{"type":"number"},"held":{"type":"number"},"resetsAt":{"type":"number"},"attempt":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"card":{"type":["object","null"],"properties":{"brand":{"type":"string"},"last4":{"type":"string"},"expMonth":{"type":"number"},"expYear":{"type":"number"}},"required":["brand","last4","expMonth","expYear"]},"invoiceUrl":{"type":["string","null"]},"canRetry":{"type":"boolean"},"submitted":{"type":"boolean"}},"required":["id","state","amount","fee","total","card","invoiceUrl","canRetry","submitted"]}},"required":["enabled","state","version","threshold","amount","fee","total","monthlyLimit","usedThisPeriod","held","resetsAt","attempt"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/auto-topup/disable":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Future top-ups disabled","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"state":{"type":"string","enum":["off","on","processing","cancelling","action_required","paused_declined","paused_no_card","paused_expired","limit_reached","reconcile"]},"version":{"type":"number"},"threshold":{"type":"number"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"monthlyLimit":{"type":"number"},"usedThisPeriod":{"type":"number"},"held":{"type":"number"},"resetsAt":{"type":"number"},"attempt":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"card":{"type":["object","null"],"properties":{"brand":{"type":"string"},"last4":{"type":"string"},"expMonth":{"type":"number"},"expYear":{"type":"number"}},"required":["brand","last4","expMonth","expYear"]},"invoiceUrl":{"type":["string","null"]},"canRetry":{"type":"boolean"},"submitted":{"type":"boolean"}},"required":["id","state","amount","fee","total","card","invoiceUrl","canRetry","submitted"]}},"required":["enabled","state","version","threshold","amount","fee","total","monthlyLimit","usedThisPeriod","held","resetsAt","attempt"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/auto-topup/refresh":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Refresh after a hosted billing return","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"state":{"type":"string","enum":["off","on","processing","cancelling","action_required","paused_declined","paused_no_card","paused_expired","limit_reached","reconcile"]},"version":{"type":"number"},"threshold":{"type":"number"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"monthlyLimit":{"type":"number"},"usedThisPeriod":{"type":"number"},"held":{"type":"number"},"resetsAt":{"type":"number"},"attempt":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"card":{"type":["object","null"],"properties":{"brand":{"type":"string"},"last4":{"type":"string"},"expMonth":{"type":"number"},"expYear":{"type":"number"}},"required":["brand","last4","expMonth","expYear"]},"invoiceUrl":{"type":["string","null"]},"canRetry":{"type":"boolean"},"submitted":{"type":"boolean"}},"required":["id","state","amount","fee","total","card","invoiceUrl","canRetry","submitted"]}},"required":["enabled","state","version","threshold","amount","fee","total","monthlyLimit","usedThisPeriod","held","resetsAt","attempt"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/auto-topup/retry":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"attemptId":{"type":"string","format":"uuid"}},"required":["attemptId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Retry the existing invoice","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"state":{"type":"string","enum":["off","on","processing","cancelling","action_required","paused_declined","paused_no_card","paused_expired","limit_reached","reconcile"]},"version":{"type":"number"},"threshold":{"type":"number"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"monthlyLimit":{"type":"number"},"usedThisPeriod":{"type":"number"},"held":{"type":"number"},"resetsAt":{"type":"number"},"attempt":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"total":{"type":"number"},"card":{"type":["object","null"],"properties":{"brand":{"type":"string"},"last4":{"type":"string"},"expMonth":{"type":"number"},"expYear":{"type":"number"}},"required":["brand","last4","expMonth","expYear"]},"invoiceUrl":{"type":["string","null"]},"canRetry":{"type":"boolean"},"submitted":{"type":"boolean"}},"required":["id","state","amount","fee","total","card","invoiceUrl","canRetry","submitted"]}},"required":["enabled","state","version","threshold","amount","fee","total","monthlyLimit","usedThisPeriod","held","resetsAt","attempt"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/starting-credit/grant":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartingCreditGrantInput"}}}},"responses":{"201":{"description":"The once-per-identity starting-credit grant, or its earlier identical award","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerEntry"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/adjustments":{"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustmentInput"}}}},"responses":{"201":{"description":"The entry, or the earlier one with the same idempotency key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerEntry"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/account/export":{"get":{"responses":{"200":{"description":"Everything the account stores, as a zip streamed as it is read: agents' configuration and history, definitions, channels, webhooks, volumes' files, and the credit ledger and usage (see its README.txt). Secrets and keys are left out","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/account":{"delete":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeletionInput"}}}},"responses":{"202":{"description":"The account is being deleted: it stops signing in and authenticating now, and its data goes within minutes. Its credit ledger, usage and payment records are kept for accounting; remaining credit is forfeited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeletion"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tenants":{"get":{"parameters":[{"schema":{"type":"string","description":"A tenant id, GitHub login, Google address or password sign-in address"},"required":true,"description":"A tenant id, GitHub login, Google address or password sign-in address","name":"login","in":"query"}],"responses":{"200":{"description":"Tenants signed in to with that login (platform operator only)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TenantLookup"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantInput"}}}},"responses":{"201":{"description":"A prepaid tenant as a sign-up makes one, but with no GitHub or Google identity, and an API token for it, shown only once (platform operator only). Its credit comes from POST /v1/billing/adjustments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantCreated"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tenants/{id}/limits":{"put":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantLimitsInput"}}}},"responses":{"200":{"description":"Set limits for a self-serve tenant in place of its plan's (platform operator only); an admin tenant's are in the tenants file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantLimits"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tenants/{id}/password":{"put":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPasswordInput"}}}},"responses":{"200":{"description":"The tenant signs in to the console and the MCP consent page with this email address and password (platform operator, or the tenant's operator token). Its password sessions end","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPassword"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The tenant no longer signs in with a password; its password sessions end (platform operator, or the tenant's operator token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPassword"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tenants/{id}/export":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The tenant's export, as GET /v1/account/export gives it (platform operator only)","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tenants/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"202":{"description":"The tenant is being deleted, as DELETE /v1/account does (platform operator only); again, its progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeletion"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tenants/{id}/deletion":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"A deletion's progress (platform operator only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeletion"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/channels":{"get":{"responses":{"200":{"description":"The tenant's channels","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelInput"}}}},"responses":{"201":{"description":"The channel, its credentials checked (and Telegram's webhook registered)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/channels/{id}":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelUpdate"}}}},"responses":{"200":{"description":"The updated channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The channel is deleted: it stops answering, and Telegram's webhook is removed","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/definitions":{"get":{"responses":{"200":{"description":"The tenant's definitions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Definition"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"parameters":[{"schema":{"type":"string","description":"The definition's key: the same key is the same definition, set to this body (a new revision if it changes anything)"},"required":false,"description":"The definition's key: the same key is the same definition, set to this body (a new revision if it changes anything)","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefinitionInput"}}}},"responses":{"201":{"description":"The definition: at revision 1, or with a key, the key's at its latest revision; with applyOnUpdate, the agents asked to take a new one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefinitionUpdated"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/definitions/{id}":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The definition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Definition"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefinitionUpdate"}}}},"responses":{"200":{"description":"The definition at its new revision; with apply, the agents asked to take it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefinitionUpdated"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The definition is deleted; agents made from it keep their configuration","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/definitions/{id}/agents":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Live agents made from the definition, and the revision each has","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DefinitionAgent"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/runs":{"post":{"parameters":[{"schema":{"type":"string","description":"Seconds to wait for the run to end (at most 60 on create, 25 here): it answers as soon as it does, else when the wait ends, still running"},"required":false,"description":"Seconds to wait for the run to end (at most 60 on create, 25 here): it answers as soon as it does, else when the wait ends, still running","name":"wait","in":"query"},{"schema":{"type":"string","maxLength":255,"description":"Sending the same key with the same body returns the same run (while it is kept); the key with another body is a 409"},"required":false,"description":"Sending the same key with the same body returns the same run (while it is kept); the key with another body is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunInput"}}}},"responses":{"200":{"description":"The run, ended (with wait)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"202":{"description":"The run, still running: GET /v1/runs/{id} or its events for the rest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/runs/{id}":{"get":{"parameters":[{"schema":{"type":"string","description":"The run's id (run_…)"},"required":true,"description":"The run's id (run_…)","name":"id","in":"path"},{"schema":{"type":"string","description":"Seconds to wait for the run to end (at most 60 on create, 25 here): it answers as soon as it does, else when the wait ends, still running"},"required":false,"description":"Seconds to wait for the run to end (at most 60 on create, 25 here): it answers as soon as it does, else when the wait ends, still running","name":"wait","in":"query"}],"responses":{"200":{"description":"The run: running, or how it ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string","description":"The run's id (run_…)"},"required":true,"description":"The run's id (run_…)","name":"id","in":"path"}],"responses":{"200":{"description":"The run is deleted now, before its retention ends: running, it stops","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/runs/{id}/events":{"get":{"parameters":[{"schema":{"type":"string","description":"The run's id (run_…)"},"required":true,"description":"The run's id (run_…)","name":"id","in":"path"},{"schema":{"type":"string","description":"Resume after this event id. Without one, or one the stream no longer has, it starts with a snapshot of the run so far"},"required":false,"description":"Resume after this event id. Without one, or one the stream no longer has, it starts with a snapshot of the run so far","name":"last-event-id","in":"header"}],"responses":{"200":{"description":"Server-sent events as an agent's (`id: <cursor>`, `data: <ClientEvent>`), after a `ready` frame, ending with the run's `response`. A run that ended a while ago answers with its response alone; its messages are at /messages","content":{"text/event-stream":{"schema":{"type":"string"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/runs/{id}/messages":{"get":{"parameters":[{"schema":{"type":"string","description":"The run's id (run_…)"},"required":true,"description":"The run's id (run_…)","name":"id","in":"path"}],"responses":{"200":{"description":"The run's messages: its input, the model's turns and tool results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/History"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/runs/{id}/abort":{"post":{"parameters":[{"schema":{"type":"string","description":"The run's id (run_…)"},"required":true,"description":"The run's id (run_…)","name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"The run is aborted: it ends failed, code aborted","content":{"application/json":{"schema":{"type":"object","properties":{"aborted":{"type":"boolean","enum":[true]}},"required":["aborted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/mounts":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The agent's mounts","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Mount"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MountsInput"}}}},"responses":{"200":{"description":"The agent's new mounts","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Mount"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes":{"get":{"parameters":[{"schema":{"type":"string","description":"Comma-separated volume ids (at most 50): those volumes, each with its seq, files and bytes (Volume), instead of every volume"},"required":false,"description":"Comma-separated volume ids (at most 50): those volumes, each with its seq, files and bytes (Volume), instead of every volume","name":"ids","in":"query"}],"responses":{"200":{"description":"The tenant's volumes; with ids, those volumes as they are now","content":{"application/json":{"schema":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/VolumeSummary"},{"$ref":"#/components/schemas/Volume"}]}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeInput"}}}},"responses":{"201":{"description":"The volume","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Volume"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The volume","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Volume"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The volume is deleted; agents mounting it can no longer reach it","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/snapshots":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"key:value; repeat it for several. Only snapshots with every label given"},"required":false,"description":"key:value; repeat it for several. Only snapshots with every label given","name":"label","in":"query"}],"responses":{"200":{"description":"The volume's snapshots, oldest first","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Snapshot"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotInput"}}}},"responses":{"201":{"description":"The snapshot: a copy of the file metadata, sharing contents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotMade"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/snapshots/{snapshotId}":{"patch":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"snapshotId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotUpdate"}}}},"responses":{"200":{"description":"The snapshot as it is now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshot"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"snapshotId","in":"path"},{"schema":{"type":"string","enum":["true"],"description":"Delete a pinned snapshot too"},"required":false,"description":"Delete a pinned snapshot too","name":"force","in":"query"}],"responses":{"200":{"description":"The snapshot is deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"409":{"description":"The snapshot is pinned: unpin it, or pass force=true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/archive":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Archive a snapshot (a project's version) instead of the volume as it is"},"required":false,"description":"Archive a snapshot (a project's version) instead of the volume as it is","name":"snapshot","in":"query"},{"schema":{"type":"string","description":"Only the files under this directory (default /); their names in the archive are relative to it"},"required":false,"description":"Only the files under this directory (default /); their names in the archive are relative to it","name":"path","in":"query"},{"schema":{"type":"string","description":"Only files matching this pattern, relative to path (e.g. **/*.ts)"},"required":false,"description":"Only files matching this pattern, relative to path (e.g. **/*.ts)","name":"glob","in":"query"}],"responses":{"200":{"description":"A tar.gz of the files, as the volume (or the snapshot) has them at one seq, named relative to path; X-Volume-Seq is that seq. At most 10,000 files and 1 GiB, else 413","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/restore":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreInput"}}}},"responses":{"200":{"description":"The volume is as the snapshot was: what it lacked is removed, what differed is written, each a change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Restored"}}}},"404":{"description":"Unknown volume or snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/fork":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForkInput"}}}},"responses":{"201":{"description":"A new, independent volume with the same files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Volume"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{id}/links":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/LinkInput"},{"type":"object","properties":{"path":{"type":"string","description":"The file's path as the agent sees it, in one of its mounts (e.g. /workspace/report.pdf)"}}}]}}}},"responses":{"201":{"description":"A signed URL for one of the agent's files, usable without a token until it expires","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/links":{"post":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":255,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409"},"required":false,"description":"Retrying with the same key (within a day) replays the first success instead of acting again; the key with another request is a 409","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkInput"}}}},"responses":{"201":{"description":"A signed URL for one file, usable without a token until it expires","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/changes":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Changes after this seq"},"required":false,"description":"Changes after this seq","name":"since","in":"query"},{"schema":{"type":"string","description":"Only changes at or under this path"},"required":false,"description":"Only changes at or under this path","name":"prefix","in":"query"}],"responses":{"200":{"description":"Recent changes, oldest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Changes"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/files":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"prefix","in":"query"},{"schema":{"type":"string"},"required":false,"name":"glob","in":"query"},{"schema":{"type":"string"},"required":false,"name":"after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"List (or read) a snapshot of the volume instead of the volume as it is"},"required":false,"description":"List (or read) a snapshot of the volume instead of the volume as it is","name":"snapshot","in":"query"},{"schema":{"type":"string","enum":["true"],"description":"Every matching file with its contents, in one answer at one seq (FileContents): at most 1,000 files and 16 MiB, else 413"},"required":false,"description":"Every matching file with its contents, in one answer at one seq (FileContents): at most 1,000 files and 16 MiB, else 413","name":"content","in":"query"}],"responses":{"200":{"description":"Files under prefix, in path order, a page at a time; with content=true, all of them with their contents (FileContents)","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/FileList"},{"$ref":"#/components/schemas/FileContents"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/files/{path}":{"put":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Path inside the volume; may contain /"},"required":true,"description":"Path inside the volume; may contain /","name":"path","in":"path"},{"schema":{"type":"string","description":"Only replace this version"},"required":false,"description":"Only replace this version","name":"if-match","in":"header"},{"schema":{"type":"string","description":"* to create only"},"required":false,"description":"* to create only","name":"if-none-match","in":"header"}],"requestBody":{"description":"The file's bytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"The file's new version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolumeFile"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Path inside the volume; may contain /"},"required":true,"description":"Path inside the volume; may contain /","name":"path","in":"path"},{"schema":{"type":"string","description":"Read the file as a snapshot of the volume has it"},"required":false,"description":"Read the file as a snapshot of the volume has it","name":"snapshot","in":"query"},{"schema":{"type":"string","description":"bytes=start-end"},"required":false,"description":"bytes=start-end","name":"range","in":"header"}],"responses":{"200":{"description":"The file, streamed a chunk at a time; its version is X-File-Version (and the ETag, which a proxy may rewrite)","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"The requested range","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Path inside the volume; may contain /"},"required":true,"description":"Path inside the volume; may contain /","name":"path","in":"path"},{"schema":{"type":"string"},"required":false,"name":"if-match","in":"header"}],"responses":{"200":{"description":"The file is deleted","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"deleted":{"type":"boolean","enum":[true]},"seq":{"type":"number"}},"required":["path","deleted","seq"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"run.started":{"post":{"summary":"run.started","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event_run_started"}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else, or no answer within 10 seconds, is retried"}}}},"run.completed":{"post":{"summary":"run.completed","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event_run_completed"}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else, or no answer within 10 seconds, is retried"}}}},"run.failed":{"post":{"summary":"run.failed","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event_run_failed"}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else, or no answer within 10 seconds, is retried"}}}},"input.requested":{"post":{"summary":"input.requested","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event_input_requested"}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else, or no answer within 10 seconds, is retried"}}}},"input.resolved":{"post":{"summary":"input.resolved","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event_input_resolved"}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else, or no answer within 10 seconds, is retried"}}}},"usage.recorded":{"post":{"summary":"usage.recorded","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event_usage_recorded"}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else, or no answer within 10 seconds, is retried"}}}}}}