{"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"},"stopped":{"type":"string","enum":["input_required","spend_limit"],"description":"Why it stopped early: waiting on input (inputIds), or a spend limit"},"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"},"error":{"type":"string"},"uncertain":{"type":"boolean","description":"A restart cut it short: its effects are unknown"},"steeredInto":{"type":"string"}},"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"},"requestId":{"type":["string","null"]},"subject":{"type":"string"},"actor":{"type":["string","null"]},"context":{"type":"object","additionalProperties":{}},"keyScope":{"type":["string","null"]},"provider":{"type":"string"},"model":{"type":"string"},"kind":{"type":"string","enum":["response","compaction"]},"input":{"type":"number"},"output":{"type":"number"},"cacheRead":{"type":"number"},"cacheWrite":{"type":"number"},"reasoning":{"type":"number"},"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"},"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); INTERNAL (500); 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); 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). Others may be added"}},"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"]},"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 address or GitHub login it signed in with"},"name":{"type":"string","description":"The person's display name, for console sessions signed in with Google or GitHub"},"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, billed to prepaid credit"},"last4":{"type":"string"},"setAt":{"type":"number"}},"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"},"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"}},"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"}},"required":["id","url","events","createdAt"]},"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"]},"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"}},"required":["url","createdAt"]},"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"},"available":{"type":"boolean","description":"Whether this tenant has a key for the provider"}},"required":["id","provider","modelId","name","api","reasoning","input","contextWindow","maxTokens","cost","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"},"connected":{"type":"boolean"},"running":{"type":"boolean"},"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"}},"required":["id","key","name","type","model","connected","running","expiresAt","resume"]},"AgentCreated":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string","description":"The agent's scoped credential for /clients routes"},"expiresAt":{"type":["number","null"]},"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"}},"required":["id","token","expiresAt"],"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"},"steeredInto":{"type":"string","description":"A prompt with whileRunning: steer that a running turn took: that turn's request, whose outcome this shares"},"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"],"description":"Why an ended run stopped early (outcome.result.stopped)"}},"required":["id","method","state","fingerprint"]},"Outcome":{"type":"object","properties":{"result":{},"error":{"type":"string"},"uncertain":{"type":"boolean"}},"description":"result.stopped is input_required when the turn waits on human input, listed in result.inputs"},"AgentInput":{"type":"object","properties":{"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 and fileTools 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"]},"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"},"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"},"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"},"mounts":{"type":"array","items":{"$ref":"#/components/schemas/Mount"},"description":"Volumes for the agent's file tools; default: a new workspace volume at /workspace"},"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), for an agent without a definition; one made from a definition has its definition's. An upsert without builtins 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"},"modelHeaders":{"$ref":"#/components/schemas/ModelHeaders"},"prompt":{"$ref":"#/components/schemas/PromptInput"}}},"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"]},"Builtin":{"type":"string","enum":["web_fetch","web_search","schedule","ask_user"]},"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\""},"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"},"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, and this request ends with that turn (steeredInto names it); 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"}]},"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}"}},"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"}},"required":["data"],"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"}},"required":["text"],"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"},"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"},"spendLimit":{"type":["object","null"],"properties":{"usd":{"type":"number"},"spent":{"type":"number","description":"Model spend since the limit was set"}},"required":["usd","spent"]},"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","spendLimit","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"]},"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"},"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"]},"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"]},"description":"What it reads of the agent: GET /v1/agents/{id}/<scope>. Default all four"},"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). 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)"}}},"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"]},"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"},"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"}},"additionalProperties":false,"description":"On an agent made from a definition, a model or thinkingLevel 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"},"dueAt":{"type":"number"},"everySeconds":{"type":"number"},"createdAt":{"type":"number"}},"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"},"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"]},"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"]},"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"],"description":"turn: the agent's own responses; compaction: summaries of older context"}},"required":["responses","input","output","cacheRead","cacheWrite","cost","platformResponses","platformCost","day","model","kind"]}}},"required":["since","totals","days"]},"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)"},"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)"}},"required":["agentHour","storageGbMonth","openrouterCreditMultiplier","purchaseFeeBps","minPurchase","maxPurchase","webSearch","webRender"],"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","startingCredit","month","recent","rates"]},"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"]},"createdAt":{"type":"number"}},"required":["tenant","github","googleEmail","createdAt"]},"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"]},"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"},"limits":{"$ref":"#/components/schemas/DefinitionLimits"},"mounts":{"type":"array","items":{"$ref":"#/components/schemas/Mount"},"maxItems":16,"description":"Volumes for each agent's file tools; default: a new workspace volume per agent"},"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, billed 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"},"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"}},"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"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"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"}}},"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)"},"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"},"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"]},"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)"},"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"},"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"]},"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"]},"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"},"limits":{"$ref":"#/components/schemas/DefinitionLimits"},"mounts":{"type":"array","items":{"$ref":"#/components/schemas/Mount"},"maxItems":16,"description":"Volumes for each agent's file tools; default: a new workspace volume per agent"},"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, billed 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"},"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"},"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"}},"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)"},"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"},"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)"},"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"},"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"]},"DefinitionUpdated":{"allOf":[{"$ref":"#/components/schemas/Definition"},{"type":"object","properties":{"applied":{"type":"array","items":{"$ref":"#/components/schemas/ApplyResult"},"description":"With apply: \"all\", 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"]},"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]},"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"},"limits":{"allOf":[{"$ref":"#/components/schemas/DefinitionLimits"},{"type":["object","null"]}]},"mounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Mount"},"maxItems":16,"description":"Volumes for each agent's file tools; default: a new workspace volume per agent"},"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, billed 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"},"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"},"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"},"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"]},"MountsInput":{"type":"object","properties":{"mounts":{"type":"array","items":{"$ref":"#/components/schemas/Mount"}}},"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"}}},"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"}},"required":["id","volume","name","seq","createdAt","files","bytes"]},"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"]}},"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/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/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"},"required":false,"description":"Only models this tenant has a key for","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"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentInput"}}}},"responses":{"201":{"description":"The agent and its scoped token","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}/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","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"}],"responses":{"200":{"description":"The running turn is 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}/prompt":{"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/PromptInput"}}}},"responses":{"202":{"description":"The accepted request","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"}],"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/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 within seconds","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean","enum":[true]}},"required":["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","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean","enum":[true]}},"required":["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/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 or Google address"},"required":true,"description":"A tenant id, GitHub login or Google 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"}}}}}}},"/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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Definition"}}}},"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/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":{"responses":{"200":{"description":"The tenant's volumes","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VolumeSummary"}}}}},"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"}],"responses":{"200":{"description":"The volume's snapshots","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/VolumeInput"}}}},"responses":{"201":{"description":"The snapshot: a copy of the file metadata, sharing contents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshot"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/volumes/{id}/snapshots/{snapshotId}":{"delete":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"snapshotId","in":"path"}],"responses":{"200":{"description":"The snapshot 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/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"}],"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"}],"responses":{"200":{"description":"Files under prefix, in path order, a page at a time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileList"}}}},"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":"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"}}}}}}