{"openapi":"3.1.0","info":{"title":"Gobare Agent API","version":"v1","description":"Programmatic access to Gobare coding-agent sessions. Conceptually aligned with OpenAI's Agents API; deliberately not wire-compatible with it. See the divergence list in the product documentation."},"servers":[{"url":"https://api.{domain}","variables":{"domain":{"default":"gobare.dev"}}}],"components":{"securitySchemes":{"accessToken":{"type":"http","scheme":"bearer","description":"A `gbr_pat_` access token. Scopes are recorded on the token when it is minted."}},"schemas":{"Error":{"type":"object","required":["error"],"description":"Every refusal this API makes, in one shape.","properties":{"error":{"description":"Always present on a failure, and the only thing present.","type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","authentication_error","permission_denied","not_found","method_not_allowed","conflict","queue_full","rate_limit_exceeded","project_limit_exceeded","context_length_exceeded","provider_error","provider_unauthorized","sandbox_error","sandbox_unavailable","directory_unavailable","workspace_recovery_failed","bridge_incompatible","internal_error"]},"message":{"type":"string"},"request_id":{"type":"string","description":"Also on the x-request-id header. Quote it when reporting a problem."}}}}},"OpenApiDocument":{"type":"object","description":"This document. Described so every route's declared schema resolves.","required":["openapi","info","paths"],"properties":{"openapi":{"type":"string"},"info":{"type":"object"},"paths":{"type":"object"}}},"SessionList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"has_more":{"type":"boolean"},"last_id":{"type":["string","null"]}}},"TurnList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Turn"}},"has_more":{"type":"boolean"},"last_id":{"type":["string","null"]}}},"ItemList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"has_more":{"type":"boolean"},"last_id":{"type":["string","null"]}}},"Session":{"type":"object","required":["object","id","status","created_at","updated_at","agent","environment","preview"],"properties":{"object":{"type":"string","const":"session","description":"Always `session`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string","description":"Ours, not yours. Use `metadata` to carry your own identifier."},"title":{"type":["string","null"],"description":"A label for people. Set it yourself; nothing derives one."},"status":{"type":"string","enum":["idle","working","requires_action","failed"],"description":"`idle` accepts input. `working` is running a turn. `requires_action` is waiting on you — see `required_actions`. `failed` is the last turn's outcome, not a dead session."},"created_at":{"type":"integer","description":"Unix milliseconds."},"updated_at":{"type":"integer","description":"Unix milliseconds. Moves on any change, including the workspace waking."},"source":{"type":["string","null"],"enum":["api","console","cli",null],"description":"Which door created this session. Null on sessions predating the field."},"created_by_token":{"type":["string","null"],"description":"The id of the access token that created it — never its secret."},"agent":{"type":"object","description":"What is running, and how freely.","properties":{"id":{"type":["string","null"],"description":"The agent template this session was created from, or null when it was configured inline. Still here after that template is deleted — it is history, not a live reference, which is what makes it usable for answering \"where did this session's settings come from\" long after the fact. The response has carried it since the field existed; it was simply never described here."},"model":{"type":["string","null"],"description":"The model this session is bound to. Fixed at creation."},"model_credential_id":{"type":["string","null"],"description":"The connection it runs on. `GET /v1/model-credentials` lists them."},"approval_mode":{"type":["string","null"],"description":"How much the agent may do without asking."},"instructions":{"type":["string","null"],"maxLength":32000},"permission_rules":{"type":"array","items":{"type":"object"}},"tools":{"type":"array","items":{"type":"object"},"description":"What this session can call, as you configured it, with any secrets removed. On the single-session read only — a page of sessions does not carry it."}}},"environment":{"type":"object","description":"The workspace: its state, where the agent works, and the repository bound to it.","properties":{"type":{"type":"string","const":"sandbox"},"state":{"type":"string","enum":["unknown","running","paused","destroyed","recovering","recovery_failed"],"description":"Where the workspace is. `unknown` until it first reports — a session is created before its sandbox exists, so this is what you see immediately after POST /v1/sessions. `running` is usable; `paused` is idle and woken by the next thing you send; `destroyed` is reclaimed and will be rebuilt on demand; `recovering` and `recovery_failed` are a rebuild in progress and one that gave up. A value outside this set is reported as null rather than passed through."},"workspace_directory":{"type":"string"},"repo":{"type":["object","null"],"description":"The repository bound to this session, once one is. Null when none was asked for.","properties":{"full_name":{"type":"string","description":"owner/name, as given."},"branch":{"type":["string","null"],"description":"Reported by the clone, not chosen. Null until the workspace comes up."},"clone_error":{"type":["string","null"],"description":"Why the clone did not happen, when it did not."}}}}},"preview":{"type":"object","description":"Addresses for whatever the agent is serving. See preview.md.","properties":{"url":{"type":["string","null"]},"port":{"type":["integer","null"]},"published_url":{"type":["string","null"]}}},"required_actions":{"type":"array","description":"Everything the session is waiting on you for. Authoritative — not a replay of events, so a caller that restarted gets the same complete answer.","items":{"$ref":"#/components/schemas/RequiredAction"}}}},"RequiredAction":{"type":"object","required":["type","turn_id","call_id"],"description":"Something this session is waiting for. Copy turn_id and call_id into the result you submit.","properties":{"type":{"type":"string","enum":["function_call","approval","question"],"description":"What is being asked of you. `function_call` you answer through the API; `approval` and `question` are answered by a person in the Console."},"turn_id":{"type":"string","description":"Copy this back when answering."},"call_id":{"type":"string","description":"Copy this back when answering. It identifies which call the result is for."},"name":{"type":["string","null"],"description":"The function the agent wants to call, as you declared it."},"arguments":{"description":"What it wants to call the function with. Shaped by your own parameter schema."},"created_at":{"type":"integer","description":"Unix milliseconds, when the agent asked."},"expires_at":{"type":["integer","null"],"description":"Unix milliseconds, when this stops being waited for — set from the tool's own `timeout_seconds`. Null, the default, means it waits indefinitely. Past this the call is answered as failed and the turn continues; the turn itself does not fail."}}},"Turn":{"type":"object","required":["object","id","session_id","status","created_at"],"properties":{"object":{"type":"string","const":"turn","description":"Always `turn`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string","description":"Ours. Quote it when reporting a problem with this turn."},"session_id":{"type":"string","description":"The session this turn belongs to."},"status":{"type":"string","enum":["working","completed","failed","cancelled"],"description":"`working` covers everything before it settles, including a turn parked on a tool result from you — watch the session's `requires_action` for that, not this field. `completed`, `failed` and `cancelled` are settled; a settled turn never moves again."},"created_at":{"type":"integer","description":"Unix milliseconds, when the input was accepted."},"started_at":{"type":["integer","null"],"description":"When the agent began. Null until it does — a turn is `working` from the moment it is accepted, including while it waits behind another one, so this is the only field that tells the two apart. `queued` was removed from `status`; this description still named it."},"completed_at":{"type":["integer","null"],"description":"When it settled. Null until it has."},"artifacts":{"type":["string","null"],"enum":["pending","ready","partial","failed",null],"description":"Whether this turn's artifacts can be fetched yet. Publication runs after the turn settles, so an empty artifact list under `pending` means not yet, and under `ready` means the turn produced nothing. `partial` means publishing finished and left something behind — read `artifacts_skipped` for what and why."},"artifacts_skipped":{"type":"array","description":"Files publishing did not take, and why. Empty unless `artifacts` is `partial`. A file past the per-file ceiling, or one that did not fit in what the turn had left, is reported here rather than disappearing.","items":{"type":"object","required":["path","reason"],"properties":{"path":{"type":"string","description":"The path inside the workspace, as the agent wrote it."},"reason":{"type":"string","description":"Why it was not taken. Written for a person, not branched on."}}}},"subagent_id":{"type":["string","null"],"description":"Always null today; reserved for delegation."},"error":{"type":["object","null"],"description":"Why it failed, when it did. Null otherwise."}}},"Item":{"type":"object","required":["object","id","session_id","type","created_at"],"properties":{"object":{"type":"string","const":"item","description":"Always `item`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string","description":"Ours. Stable; use it as a paging cursor."},"session_id":{"type":"string","description":"The session this item belongs to."},"type":{"type":"string","enum":["message","tool_call","command_execution","file_change","approval","question","mcp_unavailable","error"],"description":"What kind of thing happened. Decides which of `content` and `detail` carries the substance. `error` says a run could not start or could not continue, and `detail.message` says why."},"created_at":{"type":"integer","description":"Unix milliseconds."},"role":{"type":"string","enum":["user","assistant"],"description":"On `message` items only: who said it."},"content":{"type":"string","description":"The text of a `message`. Empty on other kinds."},"detail":{"type":"object","description":"Everything kind-specific: the command run, the path changed, the arguments passed. `examples` carries a real one per item type. `detail.event` is the *event* name — items and events share one vocabulary, and that field is the join between them. It is also how the two halves of `tool_call` are told apart: a call and its result are both `type: \"tool_call\"`, and only `detail.event` says which. There is no `tool_result` item type; code written from the enum alone renders every tool call twice.","examples":{"message":{"event":"agent.message","text":"I found the regression in export-svc v2.3.2."},"tool_call":{"event":"agent.tool_call","toolCallId":"call_53ce8a1f","toolName":"write","args":{"path":"/workspace/outputs/report.md"}},"command_execution":{"event":"agent.tool_result","toolCallId":"call_1c72fe08","toolName":"bash","exitCode":0,"summary":"restarting checkout"},"file_change":{"event":"file.modified","path":"/workspace/src/export.ts","kind":"modified"},"approval":{"event":"approval.requested","toolCallId":"call_9a1f20bd","name":"bash","args":{"command":"systemctl restart export"}},"question":{"event":"question.asked","toolCallId":"call_7be1c4d0","question":"Roll back or patch forward?"},"mcp_unavailable":{"event":"mcp.unavailable","name":"runbook","reason":"the server did not answer within 10s"},"error":{"event":"agent.error","message":"the model provider returned 502"},"tool_call (result)":{"event":"agent.tool_result","toolCallId":"call_53ce8a1f","toolName":"write","isError":false,"summary":"Successfully wrote 5 bytes"}}}}},"EventStream":{"type":"object","description":"A server-sent event. The response is text/event-stream, not JSON; this describes one frame's data.","required":["object","type","session_id","created_at"],"properties":{"object":{"type":"string","const":"event","description":"Always `event`. Names the shape, so a value can be identified without knowing which call returned it."},"type":{"type":"string","description":"The event's name. See events.md for the vocabulary."},"internal_type":{"type":"string","description":"The control plane's own name for the event, for cross-referencing logs."},"session_id":{"type":"string","description":"The session it happened in."},"seq":{"type":["integer","null"],"description":"Cursor for Last-Event-ID. Null on a transient event, which does not advance it."},"created_at":{"type":"integer","description":"Unix milliseconds."},"payload":{"type":"object","description":"Everything specific to this event type. Not one shape — `examples` below carries a real payload for every type in the vocabulary, keyed by the type. Read the one you are handling rather than probing for fields: `agent.tool_call` carries `toolName` and `args`, not `name` and `arguments`, and guessing that pair wrong renders every tool call as an empty object.","examples":{"turn.started":{"turnId":"turn_1bdef0a94c2e47f3"},"turn.ended":{"turnId":"turn_1bdef0a94c2e47f3"},"agent.text":{"delta":"Looking at the export handler"},"agent.thinking":{"delta":"The error rate started at 09:12"},"agent.message":{"text":"I found the regression in export-svc v2.3.2."},"agent.tool_call":{"toolCallId":"call_53ce8a1f","toolName":"write","args":{"path":"/workspace/outputs/report.md","content":"# Report"}},"agent.tool_result":{"toolCallId":"call_53ce8a1f","toolName":"write","isError":false,"cancelled":false,"summary":"Successfully wrote 5 bytes"},"agent.compaction":{"before":182000,"after":41000},"agent.error":{"message":"the model provider returned 502"},"agent.todos":{"items":[{"label":"Read the alert","status":"done"},{"label":"Write the postmortem","status":"pending"}]},"user.message":{"text":"Alert A-4471: export error rate 12%."},"message.queued":{"text":"Also check the retry queue.","position":1},"message.dequeued":{"text":"Also check the retry queue."},"file.changed":{"path":"/workspace/src/export.ts","kind":"modified","diff":"@@ -1,3 +1,4 @@\n…"},"approval.requested":{"toolCallId":"call_9a1f20bd","name":"bash","args":{"command":"systemctl restart export"},"sensitive":true},"approval.resolved":{"toolCallId":"call_9a1f20bd","approved":true},"question.asked":{"toolCallId":"call_7be1c4d0","question":"Roll back or patch forward?","options":["roll back","patch"],"allowFreeform":true},"question.answered":{"toolCallId":"call_7be1c4d0","answer":"roll back"},"tool.required":{"toolCallId":"call_4f01aa27","name":"lookup_order","arguments":{"order_id":"A-4471"}},"tool.resolved":{"toolCallId":"call_4f01aa27","name":"lookup_order","success":true},"sandbox.created":{"state":"running"},"sandbox.paused":{"state":"paused"},"sandbox.resumed":{"state":"running"},"preview.ready":{"port":3000,"url":"https://p-4f1c8e02a7b1.gobare.dev"},"workspace.recovery_failed":{"message":"no snapshot was available for this workspace"},"artifact.created":{"id":"art_6f2a9c41","path":"/workspace/outputs/report.md","size_bytes":482,"turn_id":"turn_1bdef0a94c2e47f3"},"mcp.unavailable":{"name":"runbook","reason":"the server did not answer within 10s"},"gobare.replay_truncated":{"from_seq":91204,"note":"More than 50000 events were waiting."}}}}},"SessionCreateRequest":{"type":"object","example":{"agent":{"model":"MiniMax-M3"},"input":"Write /workspace/outputs/report.md about this repo."},"description":"Everything optional. A session with only a model is a complete session.","properties":{"agent":{"$ref":"#/components/schemas/AgentConfig","description":"What runs, and how freely. Omit every field and the organization's default connection runs it."},"environment":{"type":"object","description":"What the workspace starts with.","properties":{"template_id":{"type":"string","description":"Deprecated name for an agent id."},"profiles":{"type":"array","items":{"type":"string"},"description":"Environment-variable group ids. GET /v1/environment-profiles lists them."},"repo":{"type":"string","description":"`owner/name`. A URL is refused; the branch is reported by the clone, not chosen."},"files":{"type":"array","description":"Files to place in the workspace before the first turn.","items":{"$ref":"#/components/schemas/SeedFile"}}}},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own labels. Returned unchanged; never interpreted."},"input":{"type":"string","description":"An opening message. All or nothing — if it cannot be accepted the session is not created either."},"title":{"type":"string","description":"A label for people."}}},"AgentConfig":{"type":"object","description":"What runs, and how freely.","properties":{"id":{"type":"string","description":"An agent to inherit from. Per-field overrides still apply."},"model":{"type":"string","description":"Must be one the chosen credential runs."},"model_credential_id":{"type":"string","description":"Omit to use the organization's default."},"instructions":{"type":["string","null"],"maxLength":32000,"description":"Standing instructions for every turn. `null` clears an inherited one."},"approval_mode":{"type":"string","enum":["auto","per_step","read_only","plan"],"description":"How much the agent may do without asking."},"permission_rules":{"type":"array","items":{"type":"object"},"description":"Path rules evaluated before a write."},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolRequest"},"description":"What the agent may reach outside the workspace: your own functions, MCP servers, and which built-ins. Everything inside the workspace — shell, files, git — is always there and is not configured here."},"text":{"$ref":"#/components/schemas/TextConfig","description":"Shaping the final message: how much it says, and whether it must conform to a JSON Schema."}}},"SessionPatchRequest":{"type":"object","example":{"title":"Nightly report","metadata":{"run":"42"}},"description":"Only the fields present are changed.","properties":{"title":{"type":["string","null"],"description":"`null` clears it."},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"`null` clears every label."},"agent":{"type":"object","description":"Change what runs, mid-session. The workspace and the transcript are kept either way.","properties":{"model":{"type":"string","description":"Move this running session to another connection. Send with `model_credential_id`; the workspace and the transcript are kept."},"model_credential_id":{"type":"string","description":"The connection to move to. It must offer the named model — one connection runs one model."},"instructions":{"type":["string","null"],"description":"Standing instructions from the next turn on. `null` clears an inherited one."},"approval_mode":{"type":"string","enum":["auto","per_step","read_only","plan"],"description":"How much the agent may do without asking, from the next turn on."},"permission_rules":{"type":"array","items":{"type":"object"},"description":"Path rules evaluated before a write. Replaces the existing rules rather than adding to them."}}}}},"ToolsRequest":{"type":"object","example":{"tools":[{"type":"function","name":"lookup_order","description":"Look up an order.","parameters":{"type":"object","properties":{"order_id":{"type":"string"}},"required":["order_id"]}}]},"description":"What the agent may call. Replaces the session's whole configuration — entries are not merged with what is already there.","properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolRequest"},"description":"What the agent may reach outside the workspace: your own functions, MCP servers, and which built-ins. Everything inside the workspace — shell, files, git — is always there and is not configured here. An empty array leaves the session with no route to the network at all."},"text":{"$ref":"#/components/schemas/TextConfig","description":"Shaping the final message: how much it says, and whether it must conform to a JSON Schema."}}},"ToolRequest":{"type":"object","description":"One tool. `type` decides which shape applies; the fields of another are refused rather than ignored. `function` and `mcp` need a `name`; the sandbox's own networked tools are named by their `type` alone and take no other field. Naming any of the latter narrows the session to exactly the ones listed — it cannot enable one this deployment has turned off, and an empty list is a session with no way out to the network.","required":["type"],"properties":{"type":{"type":"string","enum":["function","mcp","web_search","web_fetch","image_search","browse","browser_act","screenshot"]},"name":{"type":"string","description":"`function` and `mcp` only, and required for both. What the agent calls it."},"description":{"type":"string","description":"`function` only. Read by the model to decide when to call it."},"parameters":{"type":"object","description":"`function` only. JSON Schema for the arguments."},"timeout_seconds":{"type":"integer","description":"`function` only. How long a required action may stay unanswered."},"url":{"type":"string","description":"`mcp` only. http or https endpoint of the server."},"command":{"type":"string","description":"`mcp` only. A server started inside the workspace instead of reached over the network."},"args":{"type":"array","items":{"type":"string"},"description":"`mcp` only. Arguments for `command`."},"allowed_tools":{"type":"array","items":{"type":"string"},"description":"`mcp` only. Narrow the server to these tool names."},"required":{"type":"boolean","description":"`mcp` only. `true` fails the session loudly when the server will not connect; `false` lets the turn continue with fewer tools and an `mcp.unavailable` event. Must be a boolean — a string is refused rather than read as false."},"authorization":{"type":"string","description":"`mcp` only. Sent to the server, never returned; a read-back names it under `redacted`."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"`mcp` only. Also withheld from a read-back."}}},"TextConfig":{"type":"object","description":"Shaping the final message.","properties":{"verbosity":{"type":"string","enum":["low","medium","high"],"description":"How much the agent says when it is done."},"format":{"type":"object","description":"Asked for, not enforced — see design-decisions.","properties":{"type":{"type":"string","const":"json_schema"},"schema":{"type":"object","description":"JSON Schema the final message should conform to."}}}}},"EventsRequest":{"type":"object","example":{"events":[{"type":"input.message","content":"Summarise what you found."}]},"required":["events"],"description":"One event per request. Batching has no meaning while the vocabulary is this small.","properties":{"events":{"type":"array","description":"Exactly one event. What it does depends on its `type` — send a message, answer a tool call, approve, steer or cancel.","minItems":1,"maxItems":1,"items":{"$ref":"#/components/schemas/InputEvent"}}}},"InputEvent":{"type":"object","required":["type"],"description":"The six things you can send a session. One per request.","properties":{"type":{"type":"string","enum":["input.message","input.tool_result","input.approval","input.question_answer","input.steer","input.cancel"]},"content":{"description":"For `input.message` and `input.steer`: a string, or an array of `{type,text}` parts."},"turn_id":{"type":"string","description":"For `input.tool_result`: copied from the required action."},"call_id":{"type":"string","description":"For `input.tool_result`, `input.approval` and `input.question_answer`: copied from the required action."},"success":{"type":"boolean","description":"For `input.tool_result`: whether your function worked."},"output":{"type":"string","description":"For a successful `input.tool_result`. Serialise JSON yourself."},"error":{"type":"string","description":"For a failed `input.tool_result`. Never send a thrown message — it reaches the model."},"approved":{"type":"boolean","description":"For `input.approval`: whether the agent may proceed. Required, and not defaulted either way — denying something you meant to allow is a mistake, and the other direction is worse."},"answer":{"type":"string","description":"For `input.question_answer`: what to tell the agent. It reaches the model as written."}}},"AgentCreateRequest":{"type":"object","example":{"name":"reviewer","model":"MiniMax-M3","instructions":"Review diffs. Never modify files."},"required":["name"],"properties":{"name":{"type":"string","description":"Yours, for recognising it."},"model":{"type":"string","description":"Must be one the chosen credential runs. A session started from this agent may override it."},"model_credential_id":{"type":"string","description":"Omit to use the organization's default."},"instructions":{"type":"string","maxLength":32000,"description":"Standing instructions every session started from this agent begins with."},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolRequest"},"description":"What the agent may reach outside the workspace: your own functions, MCP servers, and which built-ins. Everything inside the workspace — shell, files, git — is always there and is not configured here."},"text":{"$ref":"#/components/schemas/TextConfig","description":"Shaping the final message: how much it says, and whether it must conform to a JSON Schema."}}},"WebhookCreateRequest":{"type":"object","example":{"url":"https://you.example.com/hooks/gobare","events":["turn.completed","turn.failed"]},"required":["url"],"properties":{"url":{"type":"string","description":"https only."},"events":{"type":"array","items":{"type":"string"},"description":"Empty or absent means every event."}}},"PreviewPublishRequest":{"type":"object","example":{"subdomain":"acme-invoices"},"properties":{"subdomain":{"type":"string","description":"2–63 characters of a–z, 0–9 and hyphens. Omit and one is derived from the session."}}},"ModelCredentialCreateRequest":{"type":"object","example":{"key":"sk-ant-api03-…","label":"Anthropic"},"required":["key"],"properties":{"key":{"type":"string","description":"The provider key. Verified against the provider before it is stored, and returned nowhere afterwards."},"provider":{"type":"string","description":"Which vendor issued the key. Only needed when the prefix does not say: several vendors issue keys starting with `sk-`, and we ask rather than send your secret to vendors you never named."},"model":{"type":"string","description":"Omit to accept the connector's default."},"base_url":{"type":"string","description":"For `custom`, and for self-hosted or proxied endpoints."},"label":{"type":"string","description":"A name for the Console's list. Defaults to the provider's."},"default":{"type":"boolean","description":"Whether sessions naming no credential get this one. The first connection is always the default. Must be a boolean — a string is refused rather than read as false, because this decides whose bill every future turn lands on."}}},"FilesRequest":{"type":"object","example":{"files":[{"type":"inline","path":"data/input.csv","data":"aWQsbmFtZQoxLGFjbWU="}]},"required":["files"],"properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/SeedFile"},"description":"Files to write into the running workspace. Same shape as `environment.files`, which seeds one before the first turn."}}},"SeedFile":{"type":"object","description":"One file, inline. There is no Files API to reference and we do not fetch URLs on your behalf; for a large input use `environment.repo`.","required":["path","data"],"properties":{"type":{"type":"string","const":"inline","description":"Optional, and `inline` is the only value. Named rather than defaulted: a caller sending `file_id` has a file we cannot reach, and treating it as inline would hand them an empty workspace with no reason why."},"path":{"type":"string","description":"Where in the workspace to write it. Confined to the workspace directory."},"data":{"type":"string","description":"The file's bytes, base64. Always base64, including for text — one encoding to get right rather than two."}}},"WorkspaceFileTree":{"type":"object","required":["object","data","state"],"description":"The files in a session's workspace, as of the last snapshot. Not the live sandbox — `captured_at` says which moment this is, because reading a stale file and believing it current is the failure this field exists to prevent.","properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceFile"}},"captured_at":{"type":["integer","null"],"description":"Unix milliseconds of the snapshot. Null means none has been taken, which is not the same as an empty workspace."},"state":{"type":"string","enum":["ready","missing"],"description":"`missing` means there is no snapshot yet — call POST /files/refresh."},"truncated":{"type":"boolean","description":"The archive is read with a byte ceiling; past it the listing stops."}}},"WorkspaceFile":{"type":"object","required":["object","path","type"],"properties":{"object":{"type":"string","const":"workspace_file","description":"Always `workspace_file`. Names the shape, so a value can be identified without knowing which call returned it."},"path":{"type":"string","description":"Relative to the workspace directory."},"type":{"type":"string","enum":["file","directory"]},"size_bytes":{"type":["integer","null"],"description":"Null for a directory."},"readable":{"type":"boolean","description":"False for a directory, and for paths this API withholds — environment files and key material."}}},"WorkspaceFileContent":{"type":"object","required":["object","path","content","encoding"],"properties":{"object":{"type":"string","const":"workspace_file.content","description":"Always `workspace_file.content`. Names the shape, so a value can be identified without knowing which call returned it."},"path":{"type":"string"},"captured_at":{"type":"integer","description":"Unix milliseconds of the snapshot this came from."},"content":{"type":"string","description":"Text as text; anything else base64. `encoding` says which."},"encoding":{"type":"string","enum":["utf8","base64"]},"truncated":{"type":"boolean","description":"Text past the inline ceiling is cut. Only ever true for text."}}},"ModelConnectorCatalog":{"type":"object","required":["object","data"],"description":"The model providers this deployment can connect. Served without a token, like the OpenAPI document: it describes what the API supports rather than anything inside an organization.","properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/ModelConnector"}}}},"ModelConnector":{"type":"object","required":["object","id","display_name","protocol"],"properties":{"object":{"type":"string","const":"model_connector","description":"Always `model_connector`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string","description":"What to send as `provider` when connecting a key."},"display_name":{"type":"string"},"default_model":{"type":["string","null"],"description":"What you get by omitting `model`, and what `agent.model` must match unless you name another."},"key_prefix":{"type":["string","null"],"description":"How this vendor's keys begin. Several vendors share `sk-`, which is why connecting one of those asks for `provider` — this is how you tell which ids collide before sending a secret."},"key_url":{"type":["string","null"],"description":"Where to get a key."},"protocol":{"type":"string","enum":["anthropic","openai"],"description":"The wire protocol, which decides what a custom `base_url` must speak."},"default_base_url":{"type":["string","null"]}}},"Fork":{"type":"object","description":"A new session branched from another, with its workspace and transcript. It spends a session slot like any other, and is refused by the same ceiling with the same code.","properties":{"forked_from":{"type":"string","description":"The session this was branched from. It is untouched."},"workspace_copied":{"type":"boolean","description":"Whether the workspace came with it. False means the fork starts empty — a fork is still useful without it, and believing the files are there when they are not is worse than knowing."}}},"Preview":{"type":"object","required":["object","subdomain","url","published_url","port"],"properties":{"object":{"type":"string","const":"preview","description":"Always `preview`. Names the shape, so a value can be identified without knowing which call returned it."},"subdomain":{"type":"string","description":"The label the site is served under."},"url":{"type":"string","description":"The public address. A Gobare origin, never the sandbox provider's."},"published_url":{"type":"string","description":"The same address, under the name the session object uses for it. A session carries two — `preview.url` needs a token, `preview.published_url` does not — and this call returned only `url`, so nothing in the shape said which one you were holding. It is the public one; this field says so rather than leaving you to bet on it."},"port":{"type":["integer","null"],"description":"The workspace port being served."}}},"PreviewDeleted":{"type":"object","required":["object","id","deleted"],"properties":{"object":{"type":"string","const":"preview.deleted","description":"Always `preview.deleted`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string"},"deleted":{"type":"boolean"}}},"Deleted":{"type":"object","required":["object","id","deleted"],"properties":{"object":{"type":"string","const":"session.deleted","description":"Always `session.deleted`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string"},"deleted":{"type":"boolean"}}},"InputAccepted":{"type":"object","required":["object","session_id","type"],"properties":{"object":{"type":"string","const":"input.accepted","description":"Always `input.accepted`. Names the shape, so a value can be identified without knowing which call returned it."},"session_id":{"type":"string"},"type":{"type":"string","enum":["input.message","input.cancel","input.tool_result","input.steer"]},"outcome":{"type":"string","enum":["accepted","already_resolved","not_delivered"],"description":"For input.tool_result."},"queued":{"type":"boolean","description":"The session was busy; the message is durably queued and will run."},"queue_position":{"type":["integer","null"]}}},"Tool":{"type":"object","required":["type","name"],"properties":{"type":{"type":"string","enum":["mcp","function"]},"name":{"type":"string","description":"Unique across both types: the agent sees one list."},"url":{"type":"string","description":"mcp: the server's address. Exclusive with `command`."},"command":{"type":"string","description":"mcp: a command run inside the sandbox. Exclusive with `url`."},"args":{"type":"array","items":{"type":"string"},"description":"mcp: arguments for `command`."},"allowed_tools":{"type":"array","items":{"type":"string"},"description":"mcp: restrict the agent to these tools from this server. Absent means all of them."},"required":{"type":"boolean","description":"mcp: the session fails if this server will not connect. Absent means optional, which produces an `mcp.unavailable` event instead."},"redacted":{"type":"array","items":{"type":"string"},"description":"Names of the secret values withheld from this response, such as `authorization` or `headers.x-api-key`. Not a request field: sending it back is refused, so an edited read-back cannot silently drop your credentials."},"description":{"type":"string","description":"function: what the function is for. The model reads it."},"parameters":{"type":"object","description":"function: a JSON Schema for the arguments. Carried unexamined."},"timeout_seconds":{"type":"integer","description":"function: how long to wait for your process to answer this call."}}},"ToolConfig":{"type":"object","required":["object","session_id"],"properties":{"object":{"type":"string","const":"session.tools","description":"Always `session.tools`. Names the shape, so a value can be identified without knowing which call returned it."},"session_id":{"type":"string","description":"The session this configuration applies to."},"tools":{"type":"array","description":"The configuration as sent, in the same vocabulary: one entry per tool, each with a `type` of `mcp` or `function`. Secret values are withheld — see `redacted`.","items":{"$ref":"#/components/schemas/Tool"}},"text":{"type":["object","null"],"description":"Output shaping, or null when none was set. Asked of the model, not enforced.","properties":{"verbosity":{"type":"string","enum":["low","medium","high"]},"format":{"type":"object","description":"`{type: \"json_schema\", schema: {…}}` — the shape the model is asked to answer in."}}}}},"WebhookSubscriptionCreated":{"type":"object","required":["object","id","url","events","secret"],"description":"The secret appears in this response only. Store it; it cannot be shown again.","properties":{"object":{"type":"string","const":"webhook.subscription","description":"Always `webhook.subscription`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string","description":"Ours. Use it to delete the subscription."},"url":{"type":"string","description":"Where deliveries go. Must be https."},"events":{"type":"array","description":"Which events to deliver. An empty list means all of them.","items":{"type":"string"}},"active":{"type":"boolean","description":"False once deliveries have been given up on. See webhooks.md on retries and dead letters."},"secret":{"type":"string","description":"Recompute x-gobare-signature as HMAC-SHA256 over `<timestamp>.<body>`."}}},"WebhookSubscriptionList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"WebhookSubscription":{"type":"object","required":["object","id","url","events","active"],"description":"An endpoint subscribed to session events. The secret is returned only when it is created.","properties":{"object":{"type":"string","const":"webhook.subscription","description":"Always `webhook.subscription`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string"},"url":{"type":"string","description":"Where deliveries are POSTed. https only."},"events":{"type":"array","items":{"type":"string"},"description":"What this endpoint is subscribed to."},"active":{"type":"boolean"},"created_at":{"type":"integer","description":"Unix milliseconds."},"delivery":{"$ref":"#/components/schemas/WebhookDeliveryHealth"}}},"WebhookDeliveryHealth":{"type":"object","description":"Whether this endpoint is actually receiving anything. Deliveries are retried six times over roughly nine hours and then given up on; without this, an integration whose endpoint broke found out by noticing it had stopped receiving events — the one thing webhooks exist to stop anyone having to do.","required":["pending","dead"],"properties":{"pending":{"type":"integer","description":"Owed and not yet delivered, including ones waiting on a retry."},"dead":{"type":"integer","description":"Given up on after six attempts. A number that keeps climbing means the endpoint is broken, not busy."},"last_error":{"type":["string","null"],"description":"Why the most recent one was given up on, as we saw it — a status, or the transport error."},"last_failed_at":{"type":["integer","null"],"description":"Unix milliseconds of that delivery. Null when none has been given up on."}}},"Artifact":{"type":"object","required":["object","id","session_id","turn_id","path","size_bytes"],"description":"An immutable copy of a file a turn published. Survives the sandbox being paused or reclaimed.","properties":{"object":{"type":"string","const":"artifact","description":"Always `artifact`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string","description":"Ours. Use it to fetch the bytes."},"session_id":{"type":"string","description":"The session that produced it."},"turn_id":{"type":"string","description":"The turn that published it."},"path":{"type":"string","description":"Where it was in the workspace when it was published."},"size_bytes":{"type":"integer","description":"Of the stored copy."},"content_type":{"type":"string","description":"Guessed from the path. `application/octet-stream` when unrecognised."},"created_at":{"type":"integer","description":"Unix milliseconds, when it was published."}}},"ArtifactList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}},"has_more":{"type":"boolean"},"last_id":{"type":["string","null"]}}},"ArtifactContent":{"type":"string","format":"binary","description":"The bytes. Content-Type is the artifact's own."},"WorkspaceFileList":{"type":"object","required":["object","data"],"description":"What was written into the workspace. A path that was already there has been overwritten — that is what the request asked for.","properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"type":"object","required":["object","path","size_bytes"],"properties":{"object":{"type":"string","const":"workspace_file","description":"Always `workspace_file`. Names the shape, so a value can be identified without knowing which call returned it."},"path":{"type":"string"},"size_bytes":{"type":"integer"}}}}}},"ArtifactArchive":{"type":"string","format":"binary","description":"A POSIX tar of every artifact, streamed. Narrowed to one turn with ?turn_id=, in which case entries carry the workspace path; otherwise each entry is prefixed with its turn id, because the same path published by two turns is two files. An artifact whose stored copy is gone is omitted."},"EnvironmentTemplate":{"type":"object","required":["object","id","name"],"description":"A named configuration copied into a session at creation. Changing or deleting it does not affect sessions already created from it.","properties":{"object":{"type":"string","const":"environment_template","description":"Always `environment_template`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string"},"name":{"type":"string"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"},"description":"Tools every session started from this agent gets, unless it replaces them. Secrets are withheld — see `redacted` on an entry."},"text":{"type":["object","null"],"description":"Output shaping copied into every session started from this agent."},"created_at":{"type":"integer"}}},"EnvironmentTemplateList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/EnvironmentTemplate"}}}},"Agent":{"type":"object","required":["object","id","name"],"properties":{"object":{"type":"string","const":"agent","description":"Always `agent`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string","description":"Ours. Pass it as `agent.id` when creating a session."},"name":{"type":"string","description":"Yours, for recognising it. Not an identifier."},"model":{"type":["string","null"],"description":"The model sessions from this agent run on, unless they override it."},"model_credential_id":{"type":["string","null"],"description":"The connection to run on. Null uses the organization's default."},"instructions":{"type":["string","null"],"maxLength":32000,"description":"Standing instructions given to every session started from this agent."},"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"},"description":"Tools every session started from this agent gets, unless it replaces them. Secrets are withheld — see `redacted` on an entry."},"text":{"type":["object","null"],"description":"Output shaping copied into every session started from this agent."},"created_at":{"type":"integer","description":"Unix milliseconds."}}},"AgentList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}},"ModelCredential":{"type":"object","required":["object","id","model"],"properties":{"object":{"type":"string","const":"model_credential","description":"Always `model_credential`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string","description":"Pass as agent.model_credential_id."},"label":{"type":"string","description":"Yours, from the Console. For recognising the connection."},"connector":{"type":"string","description":"Which provider integration it uses."},"model":{"type":"string","description":"agent.model must match this."},"is_default":{"type":"boolean","description":"Whether a session that names no credential gets this one."},"last4":{"type":"string","description":"The last four characters of the key. On create only; the key itself is never returned."},"verified":{"type":"boolean","description":"Whether the provider accepted a probe before this was stored."}}},"ModelCredentialList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/ModelCredential"}}}},"EnvironmentProfile":{"type":"object","required":["object","id","name"],"properties":{"object":{"type":"string","const":"environment_profile","description":"Always `environment_profile`. Names the shape, so a value can be identified without knowing which call returned it."},"id":{"type":"string"},"name":{"type":"string"},"is_default":{"type":"boolean"},"variable_count":{"type":["integer","null"]}}},"EnvironmentProfileList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","const":"list","description":"Always `list`. Names the shape, so a value can be identified without knowing which call returned it."},"data":{"type":"array","items":{"$ref":"#/components/schemas/EnvironmentProfile"}}}},"Health":{"type":"object","required":["object","status","version","scopes","usable","missing_scopes"],"properties":{"object":{"type":"string","const":"health","description":"Always `health`. Names the shape, so a value can be identified without knowing which call returned it."},"status":{"type":"string","const":"ok","description":"Always `ok`, and structurally unable to be anything else — it reports that this deployment answered, which is all a health check can promise about itself. It is not a verdict on your token. `usable` is."},"version":{"type":"string","const":"v1"},"scopes":{"type":"array","items":{"type":"string","enum":["cli","sessions:read","sessions:write","tools:respond","artifacts:read","credentials:write"]},"description":"What the presented token may do. Empty means it may do nothing here."},"usable":{"type":"boolean","description":"Whether this token can do anything under /v1 at all. `false` for one holding only `cli`, which is a real token for `gobare pi import` and refused by every route here. That token reads `{\"status\":\"ok\",\"scopes\":[\"cli\"]}` and then 403s on the first real call — the signal was in `scopes` all along, but only for a caller who already knew what to compare it against."},"missing_scopes":{"type":"array","items":{"type":"string","enum":["cli","sessions:read","sessions:write","tools:respond","artifacts:read","credentials:write"]},"description":"What to mint instead, named rather than inferred. Empty when `usable` is true."}}}}},"paths":{"/v1/health":{"get":{"summary":"Check the access token","description":"Check the access token and report what it may do.","operationId":"get_health","security":[{"accessToken":[]}],"responses":{"200":{"description":"Check the access token and report what it may do.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions":{"get":{"summary":"List sessions","description":"List the organization's sessions.","operationId":"get_sessions","security":[{"accessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return, 1–100. Default 20."},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"Newest first (`desc`, the default) or oldest first (`asc`)."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The `last_id` of the previous page. A cursor this collection cannot place — expired, deleted, or never issued — answers with an empty page rather than starting over, so a paging loop ends instead of repeating itself."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["idle","working","requires_action","failed"]},"description":"Only sessions in this state. `requires_action` is the one to ask for after a restart: it is everything waiting on your code."},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["api","console"]},"description":"`api` for sessions your code created, `console` for ones a person made in the Console. A list is organization-wide, so without this a second client sharing the organization appears in yours."},{"name":"created_by_token","in":"query","required":false,"schema":{"type":"string"},"description":"Only the sessions one token created — `me` for the token making this call. The narrowest answer to \"which of these are mine\", and the one to reach for when several integrations share an organization."},{"name":"metadata","in":"query","required":false,"schema":{"type":"string"},"description":"One of your own labels, as `key:value` — `?metadata=job:8842`. Finds the session for a job without keeping a map of your own."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"List the organization's sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionList"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a session","description":"Create a session, optionally with an opening message.","operationId":"post_sessions","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCreateRequest"}}}},"responses":{"201":{"description":"Create a session, optionally with an opening message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}":{"get":{"summary":"Retrieve a session","description":"Retrieve one session.","operationId":"get_sessions_session_id_","security":[{"accessToken":[]}],"x-required-scope":"sessions:read","responses":{"200":{"description":"Retrieve one session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a session","description":"Change a session: title, metadata, instructions, or its safety settings.","operationId":"patch_sessions_session_id_","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionPatchRequest"}}}},"responses":{"200":{"description":"Change a session: title, metadata, instructions, or its safety settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a session","description":"Delete a session and destroy its sandbox.","operationId":"delete_sessions_session_id_","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","responses":{"200":{"description":"Delete a session and destroy its sandbox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/turns":{"get":{"summary":"List turns","description":"List a session's turns.","operationId":"get_sessions_session_id_turns","security":[{"accessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return, 1–100. Default 20."},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"Newest first (`desc`, the default) or oldest first (`asc`)."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The `last_id` of the previous page. A cursor this collection cannot place — expired, deleted, or never issued — answers with an empty page rather than starting over, so a paging loop ends instead of repeating itself."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"List a session's turns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TurnList"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/turns/{turn_id}":{"get":{"summary":"Retrieve a turn","description":"Retrieve one turn.","operationId":"get_sessions_session_id_turns_turn_id_","security":[{"accessToken":[]}],"x-required-scope":"sessions:read","responses":{"200":{"description":"Retrieve one turn.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Turn"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/events":{"get":{"summary":"Stream a session's events","description":"Stream a session's events, resumable with Last-Event-ID.","operationId":"get_sessions_session_id_events","security":[{"accessToken":[]}],"parameters":[{"name":"last_event_id","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Replay durable events after this `seq`. The `Last-Event-ID` header does the same thing and is what EventSource sends on its own."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"Stream a session's events, resumable with Last-Event-ID.","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/EventStream"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Send input to a session","description":"Send input to a session: a message, a cancellation, or a tool result.","operationId":"post_sessions_session_id_events","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-any-required-scope":["sessions:write","tools:respond"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsRequest"}}}},"responses":{"202":{"description":"Send input to a session: a message, a cancellation, or a tool result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputAccepted"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events":{"get":{"summary":"Stream every session's events","description":"Stream every session the organization owns.","operationId":"get_events","security":[{"accessToken":[]}],"parameters":[{"name":"last_event_id","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Replay durable events after this `seq`. The `Last-Event-ID` header does the same thing."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"Stream every session the organization owns.","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/EventStream"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/items":{"get":{"summary":"List items","description":"List a session's durable items.","operationId":"get_sessions_session_id_items","security":[{"accessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return, 1–100. Default 20."},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"Newest first (`desc`, the default) or oldest first (`asc`)."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The `last_id` of the previous page. A cursor this collection cannot place — expired, deleted, or never issued — answers with an empty page rather than starting over, so a paging loop ends instead of repeating itself."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"List a session's durable items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemList"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/fork":{"post":{"summary":"Fork a session","description":"Branch a session, workspace and transcript included.","operationId":"post_sessions_session_id_fork","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","responses":{"201":{"description":"Branch a session, workspace and transcript included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fork"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/tools":{"put":{"summary":"Replace a session's tools","description":"Replace a session's tool configuration.","operationId":"put_sessions_session_id_tools","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolsRequest"}}}},"responses":{"200":{"description":"Replace a session's tool configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolConfig"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Read a session's tools","description":"Read a session's tool configuration.","operationId":"get_sessions_session_id_tools","security":[{"accessToken":[]}],"x-required-scope":"sessions:read","responses":{"200":{"description":"Read a session's tool configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolConfig"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"post":{"summary":"Create a webhook","description":"Subscribe an endpoint to session events.","operationId":"post_webhooks","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreateRequest"}}}},"responses":{"201":{"description":"Subscribe an endpoint to session events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionCreated"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List webhooks","description":"List the organization's webhook subscriptions.","operationId":"get_webhooks","security":[{"accessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return, 1–100. Default 20."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The `last_id` of the previous page. A cursor this collection cannot place — expired, deleted, or never issued — answers with an empty page rather than starting over, so a paging loop ends instead of repeating itself."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"List the organization's webhook subscriptions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionList"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhook_id}":{"delete":{"summary":"Delete a webhook","description":"Remove a webhook subscription.","operationId":"delete_webhooks_webhook_id_","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","responses":{"200":{"description":"Remove a webhook subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/artifacts":{"get":{"summary":"List artifacts","description":"List files this session's turns published.","operationId":"get_sessions_session_id_artifacts","security":[{"accessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return, 1–100. Default 20."},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"Newest first (`desc`, the default) or oldest first (`asc`)."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The `last_id` of the previous page. A cursor this collection cannot place — expired, deleted, or never issued — answers with an empty page rather than starting over, so a paging loop ends instead of repeating itself."},{"name":"turn_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only what this turn published."}],"x-required-scope":"artifacts:read","responses":{"200":{"description":"List files this session's turns published.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactList"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/artifacts/archive":{"get":{"summary":"Download all artifacts","description":"Download every artifact as one tar.","operationId":"get_sessions_session_id_artifacts_archive","security":[{"accessToken":[]}],"parameters":[{"name":"turn_id","in":"query","required":false,"schema":{"type":"string"},"description":"Only this turn's files, and named as the workspace had them. Without it you get the whole session, each entry prefixed with the turn that published it."}],"x-required-scope":"artifacts:read","responses":{"200":{"description":"Download every artifact as one tar.","content":{"application/x-tar":{"schema":{"$ref":"#/components/schemas/ArtifactArchive"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/artifacts/{artifact_id}":{"get":{"summary":"Retrieve an artifact","description":"Retrieve one artifact's metadata.","operationId":"get_sessions_session_id_artifacts_artifact_id_","security":[{"accessToken":[]}],"x-required-scope":"artifacts:read","responses":{"200":{"description":"Retrieve one artifact's metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete an artifact","description":"Delete a published artifact.","operationId":"delete_sessions_session_id_artifacts_artifact_id_","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","responses":{"200":{"description":"Delete a published artifact.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/artifacts/{artifact_id}/content":{"get":{"summary":"Download an artifact","description":"Download an artifact's bytes.","operationId":"get_sessions_session_id_artifacts_artifact_id_content","security":[{"accessToken":[]}],"x-required-scope":"artifacts:read","responses":{"200":{"description":"Download an artifact's bytes.","content":{"application/octet-stream":{"schema":{"$ref":"#/components/schemas/ArtifactContent"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/files":{"post":{"summary":"Write workspace files","description":"Write files into a running session's workspace.","operationId":"post_sessions_session_id_files","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilesRequest"}}}},"responses":{"200":{"description":"Write files into a running session's workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceFileList"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List workspace files","description":"List the files in a session's workspace.","operationId":"get_sessions_session_id_files","security":[{"accessToken":[]}],"parameters":[{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"`1` captures a snapshot first, so the answer is the workspace as it is now. Needs `sessions:write` — taking one is an action, not a read — and the call is refused rather than quietly answering stale if the token only holds `sessions:read`."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"List the files in a session's workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceFileTree"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/files/content":{"get":{"summary":"Read a workspace file","description":"Read one file from a session's workspace.","operationId":"get_sessions_session_id_files_content","security":[{"accessToken":[]}],"parameters":[{"name":"path","in":"query","required":false,"schema":{"type":"string"},"description":"Relative to the workspace directory."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"Read one file from a session's workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceFileContent"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/files/refresh":{"post":{"summary":"Refresh the workspace","description":"Capture a fresh snapshot of the workspace, so a read sees current files.","operationId":"post_sessions_session_id_files_refresh","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","responses":{"200":{"description":"Capture a fresh snapshot of the workspace, so a read sees current files.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceFileTree"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents":{"post":{"summary":"Create or replace an agent","description":"Create or replace a named agent.","operationId":"post_agents","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateRequest"}}}},"responses":{"201":{"description":"Create or replace a named agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List agents","description":"List the organization's agents.","operationId":"get_agents","security":[{"accessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return, 1–100. Default 20."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The `last_id` of the previous page. A cursor this collection cannot place — expired, deleted, or never issued — answers with an empty page rather than starting over, so a paging loop ends instead of repeating itself."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"List the organization's agents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentList"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{agent_id}":{"get":{"summary":"Retrieve an agent","description":"Retrieve one agent.","operationId":"get_agents_agent_id_","security":[{"accessToken":[]}],"x-required-scope":"sessions:read","responses":{"200":{"description":"Retrieve one agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete an agent","description":"Delete an agent.","operationId":"delete_agents_agent_id_","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","responses":{"200":{"description":"Delete an agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/environment-templates":{"post":{"summary":"Create an environment template","description":"Deprecated alias for POST /agents.","operationId":"post_environment_templates","deprecated":true,"security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateRequest"}}}},"responses":{"201":{"description":"Deprecated alias for POST /agents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentTemplate"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List environment templates","description":"Deprecated alias for GET /agents.","operationId":"get_environment_templates","deprecated":true,"security":[{"accessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return, 1–100. Default 20."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The `last_id` of the previous page. A cursor this collection cannot place — expired, deleted, or never issued — answers with an empty page rather than starting over, so a paging loop ends instead of repeating itself."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"Deprecated alias for GET /agents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentTemplateList"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/environment-templates/{template_id}":{"get":{"summary":"Retrieve an environment template","description":"Deprecated alias for GET /agents/{agent_id}.","operationId":"get_environment_templates_template_id_","deprecated":true,"security":[{"accessToken":[]}],"x-required-scope":"sessions:read","responses":{"200":{"description":"Deprecated alias for GET /agents/{agent_id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentTemplate"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete an environment template","description":"Deprecated alias for DELETE /agents/{agent_id}.","operationId":"delete_environment_templates_template_id_","deprecated":true,"security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","responses":{"200":{"description":"Deprecated alias for DELETE /agents/{agent_id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/environment-profiles":{"get":{"summary":"List environment profiles","description":"List the organization's environment profiles.","operationId":"get_environment_profiles","security":[{"accessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return, 1–100. Default 20."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The `last_id` of the previous page. A cursor this collection cannot place — expired, deleted, or never issued — answers with an empty page rather than starting over, so a paging loop ends instead of repeating itself."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"List the organization's environment profiles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentProfileList"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/model-connectors":{"get":{"summary":"List model providers","description":"The model providers this deployment can connect, and their defaults.","operationId":"get_model_connectors","security":[],"responses":{"200":{"description":"The model providers this deployment can connect, and their defaults.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelConnectorCatalog"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/model-credentials":{"get":{"summary":"List model connections","description":"List the organization's model connections.","operationId":"get_model_credentials","security":[{"accessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return, 1–100. Default 20."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The `last_id` of the previous page. A cursor this collection cannot place — expired, deleted, or never issued — answers with an empty page rather than starting over, so a paging loop ends instead of repeating itself."}],"x-required-scope":"sessions:read","responses":{"200":{"description":"List the organization's model connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelCredentialList"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded`. The token is past its allowance for this bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every response say how close you were.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Connect a model provider","description":"Connect a model provider with one of your own keys.","operationId":"post_model_credentials","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"credentials:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelCredentialCreateRequest"}}}},"responses":{"201":{"description":"Connect a model provider with one of your own keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelCredential"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/model-credentials/{credential_id}":{"delete":{"summary":"Remove a model connection","description":"Remove a model connection.","operationId":"delete_model_credentials_credential_id_","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"credentials:write","responses":{"200":{"description":"Remove a model connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions/{session_id}/preview":{"post":{"summary":"Publish a preview","description":"Publish this session's preview at a public URL.","operationId":"post_sessions_session_id_preview","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPublishRequest"}}}},"responses":{"201":{"description":"Publish this session's preview at a public URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preview"}}}},"400":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Unpublish a preview","description":"Take this session's preview off its public URL.","operationId":"delete_sessions_session_id_preview","security":[{"accessToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retrying with the same key replays the first answer instead of acting again."}],"x-required-scope":"sessions:write","responses":{"200":{"description":"Take this session's preview off its public URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewDeleted"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or no such object under this token's organization. Another organization's id is indistinguishable from one that never existed, deliberately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/openapi.json":{"get":{"summary":"Retrieve the OpenAPI document","description":"This API's OpenAPI 3.1 document.","operationId":"get_openapi_json","security":[],"responses":{"200":{"description":"This API's OpenAPI 3.1 document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}},"400":{"description":"`invalid_request`. A query parameter this endpoint does not take. Refused rather than ignored, because an ignored filter answers with everything and looks like a filter that matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}