{"openapi":"3.1.0","info":{"title":"AgentSky developer API","version":"1","description":"Long-lived agents over HTTP: /v1 management plus a streaming conversation plane. Auth: `Authorization: Bearer ast_…` (Settings → API tokens or `sky auth login`). Scopes: read ⊂ write ⊂ admin. Rate limit: 120 requests/min per token (429 + Retry-After). Human docs: https://agentsky.dev/docs"},"servers":[{"url":"https://api.agentsky.dev/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ast_ token"}},"schemas":{"MessagePart":{"$schema":"http://json-schema.org/draft-07/schema#","oneOf":[{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"text"},"text":{"default":"","type":"string"},"stream_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"stream_index":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["index","type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"reasoning"},"text":{"default":"","type":"string"},"redacted":{"default":false,"type":"boolean"},"stream_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"stream_index":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["index","type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"tool_call"},"call_id":{"type":"string"},"tool_name":{"type":"string"},"args":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"args_partial":{"type":["string","null"]}},"required":["index","type","call_id","tool_name"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"tool_result"},"call_id":{"type":"string"},"tool_name":{"type":"string"},"status":{"default":"ok","type":"string","enum":["ok","error"]},"result":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["index","type","call_id","tool_name"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"file"},"name":{"type":"string"},"media_type":{"type":"string"},"uri":{"type":["string","null"]},"data":{"type":["string","null"]},"size_bytes":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["index","type","name","media_type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"image"},"media_type":{"type":"string"},"uri":{"type":["string","null"]},"data":{"type":["string","null"]},"alt":{"type":["string","null"]},"width":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["index","type","media_type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"video"},"media_type":{"type":"string"},"uri":{"type":["string","null"]},"data":{"type":["string","null"]},"alt":{"type":["string","null"]},"width":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"duration_ms":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"size_bytes":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"thumbnail_uri":{"type":["string","null"]}},"required":["index","type","media_type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"status"},"level":{"type":"string","enum":["thinking","working","waiting","idle","done"]},"text":{"type":["string","null"]}},"required":["index","type","level"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"error"},"code":{"type":"string"},"message":{"type":"string"},"retryable":{"default":false,"type":"boolean"}},"required":["index","type","code","message"]}]},"CreateAgent":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"description":"Prompt/display label only — NOT the handle. The addressable handle is the auto-minted `slug` in the response","type":"string","maxLength":60},"description":{"type":"string","maxLength":500},"agentType":{"type":"string","enum":["hermes","claude_code","codex","openclaw","pi","dsh","kimi_code","opencode"]},"llm":{"type":"string"},"reasoningEffort":{"description":"Harness-native reasoning effort; omitted = the harness's own default. Allowed values depend on agentType — hermes: none/minimal/low/medium/high/xhigh/max/ultra; claude_code: low/medium/high/xhigh/max; codex: none/minimal/low/medium/high/xhigh/max; openclaw: not supported; pi: off/minimal/low/medium/high/xhigh/max; dsh: not supported; kimi_code: not supported; opencode: none/minimal/low/medium/high/xhigh/max","type":"string","enum":["none","off","minimal","low","medium","high","xhigh","max","ultra"]},"prompt":{"type":"string","maxLength":100000},"displayName":{"description":"Seeds the minted `slug` (the unique addressable handle, returned in the response); omitted = an auto-generated asteroid name","type":"string","maxLength":60},"capabilities":{"default":[],"type":"array","items":{"type":"string","enum":["exa.search","exa.contents","tinyfish.fetch","tinyfish.browser","dataforseo.serp","gptimage.generate","rembg.remove-background","seedance.generate","mm.i2v","fish-audio.transcribe"]}},"instructions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":".*\\.md$"},"content":{"default":"","type":"string"}},"required":["name"]}},"skills":{"description":"RFC-0073 skill attachments: store references ({type:'skill', skillId, version?: 'latest'|skr_…}) and GitHub shortcuts ({type:'github', url, ref?, tokenSecretRef?}). Max 20.","maxItems":20,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"skill"},"skillId":{"type":"string","minLength":1},"version":{"default":"latest","type":"string","minLength":1}},"required":["type","skillId"]},{"type":"object","properties":{"type":{"type":"string","const":"github"},"url":{"type":"string","format":"uri"},"ref":{"description":"Branch or commit SHA; default branch when omitted.","type":"string","minLength":1},"tokenSecretRef":{"description":"Agent secret key holding a clone token for private repos.","type":"string","minLength":1}},"required":["type","url"]}]}},"mcpServers":{"description":"Remote streamable-HTTP MCP servers this agent connects to.","maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"default":"url","type":"string","const":"url"},"name":{"type":"string","minLength":1,"maxLength":255},"url":{"type":"string","format":"uri"},"tools":{"type":"object","properties":{"include":{"default":[],"maxItems":200,"type":"array","items":{"type":"string","minLength":1}},"exclude":{"default":[],"maxItems":200,"type":"array","items":{"type":"string","minLength":1}}}}},"required":["name","url"]}},"customData":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","pattern":"^[a-z0-9_]+$"},"kind":{"type":"string","enum":["spreadsheet","doc","private_api","other"]},"scope":{"default":"creator","type":"string","enum":["creator","user"]},"description":{"type":"string"},"uri":{"type":"string"},"config":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["id","name","kind"]}},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"PatchAgent":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"displayName":{"type":"string","maxLength":60},"capabilities":{"type":"array","items":{"type":"string","enum":["exa.search","exa.contents","tinyfish.fetch","tinyfish.browser","dataforseo.serp","gptimage.generate","rembg.remove-background","seedance.generate","mm.i2v","fish-audio.transcribe"]}},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"harnessVersion":{"type":"string","minLength":1},"reasoningEffort":{"description":"Harness-native reasoning effort; null clears back to the harness default. Applies from the next provision/restart. Allowed values depend on agentType — hermes: none/minimal/low/medium/high/xhigh/max/ultra; claude_code: low/medium/high/xhigh/max; codex: none/minimal/low/medium/high/xhigh/max; openclaw: not supported; pi: off/minimal/low/medium/high/xhigh/max; dsh: not supported; kimi_code: not supported; opencode: none/minimal/low/medium/high/xhigh/max","anyOf":[{"type":"string","enum":["none","off","minimal","low","medium","high","xhigh","max","ultra"]},{"type":"null"}]},"skills":{"description":"Replaces the whole skills array; omitted preserves. Applies from the next provision.","maxItems":20,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"skill"},"skillId":{"type":"string","minLength":1},"version":{"default":"latest","type":"string","minLength":1}},"required":["type","skillId"]},{"type":"object","properties":{"type":{"type":"string","const":"github"},"url":{"type":"string","format":"uri"},"ref":{"description":"Branch or commit SHA; default branch when omitted.","type":"string","minLength":1},"tokenSecretRef":{"description":"Agent secret key holding a clone token for private repos.","type":"string","minLength":1}},"required":["type","url"]}]}},"mcpServers":{"description":"Replaces the whole MCP server list; omitted preserves. Applies from the next provision.","maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"default":"url","type":"string","const":"url"},"name":{"type":"string","minLength":1,"maxLength":255},"url":{"type":"string","format":"uri"},"tools":{"type":"object","properties":{"include":{"default":[],"maxItems":200,"type":"array","items":{"type":"string","minLength":1}},"exclude":{"default":[],"maxItems":200,"type":"array","items":{"type":"string","minLength":1}}}}},"required":["name","url"]}},"expectedVersion":{"type":"integer","minimum":1,"maximum":9007199254740991}}},"CreateSession":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"agent":{"type":"string","minLength":1},"llm":{"description":"Model for this session (a current model for the agent's harness). Omitted = the agent's model","type":"string","minLength":1},"reasoningEffort":{"description":"Reasoning effort for this session; omitted or null inherits the agent's setting. Allowed values depend on agentType - hermes: none/minimal/low/medium/high/xhigh/max/ultra; claude_code: low/medium/high/xhigh/max; codex: none/minimal/low/medium/high/xhigh/max; openclaw: not supported; pi: off/minimal/low/medium/high/xhigh/max; dsh: not supported; kimi_code: not supported; opencode: none/minimal/low/medium/high/xhigh/max","anyOf":[{"type":"string","enum":["none","off","minimal","low","medium","high","xhigh","max","ultra"]},{"type":"null"}]},"title":{"type":"string","maxLength":120},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"instructions":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":".*\\.md$"},"content":{"default":"","type":"string"}},"required":["name"]}},"initial_events":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"user.message"},"content":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"base64"},"media_type":{"type":"string","minLength":1},"data":{"type":"string","minLength":1}},"required":["type","media_type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"url"},"url":{"type":"string","minLength":1}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1}},"required":["type","file_id"],"additionalProperties":false}]}},"required":["type","source"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"document"},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"base64"},"media_type":{"type":"string","minLength":1},"data":{"type":"string","minLength":1}},"required":["type","media_type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"media_type":{"default":"text/plain","type":"string","const":"text/plain"},"data":{"type":"string","minLength":1}},"required":["type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"url"},"url":{"type":"string","minLength":1}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1}},"required":["type","file_id"],"additionalProperties":false}]},"title":{"type":["string","null"]},"context":{"type":["string","null"]}},"required":["type","source"],"additionalProperties":false}]}}},"required":["type","content"],"additionalProperties":false}},"environment_id":{"type":"string","minLength":1},"vault_ids":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1}},"vcpus":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"memoryMb":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"modelBilling":{"description":"Who pays for model calls: platform wallet or the user's connected subscription. Omitted = auto-apply (a connected subscription with \"use for new agents\" powers eligible compositions)","type":"string","enum":["platform","account"]},"budget":{"description":"Hard spend cap for this session. Attachable only at create; changeable or removable later via PATCH (removal is one-way)","type":"object","properties":{"type":{"type":"string","const":"limit"},"max_list_cost":{"type":"object","properties":{"amount":{"type":"string","minLength":1,"maxLength":15,"description":"Whole US cents as an integer decimal string, e.g. \"125\" for $1.25"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]}},"required":["type","max_list_cost"]},"resources":{"description":"Files and GitHub repositories mounted into the agent's working directory before its first turn (max 100). `{type:\"file\", file_id, mount_path?}` copies an upload read-only to `/workspace<mount_path>` (default `/workspace/<file_id>`); `{type:\"github_repository\", url, authorization_token?, checkout?: {type:\"branch\", name} | {type:\"commit\", sha}, mount_path?}` clones `https://github.com/{owner}/{repo}` to `/workspace<mount_path>` (default `/workspace/<repo>`); the token never enters the sandbox","maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1,"maxLength":128},"mount_path":{"anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},"required":["type","file_id"]},{"type":"object","properties":{"type":{"type":"string","const":"github_repository"},"url":{"type":"string","minLength":1,"maxLength":2048},"authorization_token":{"type":"string","minLength":1,"maxLength":1024},"checkout":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"branch"},"name":{"type":"string","minLength":1,"maxLength":255}},"required":["type","name"]},{"type":"object","properties":{"type":{"type":"string","const":"commit"},"sha":{"type":"string","minLength":7,"maxLength":64}},"required":["type","sha"]}]},{"type":"null"}]},"mount_path":{"anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},"required":["type","url"]}]}}},"required":["agent"]},"PatchSession":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"title":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"llm":{"description":"Switch this session's model (a current model for its harness; the agent's model is unchanged). Applies from the next turn","type":"string","minLength":1},"reasoningEffort":{"description":"Session-level reasoning effort; null clears back to the agent's setting. Applies from the next turn. Allowed values depend on agentType — hermes: none/minimal/low/medium/high/xhigh/max/ultra; claude_code: low/medium/high/xhigh/max; codex: none/minimal/low/medium/high/xhigh/max; openclaw: not supported; pi: off/minimal/low/medium/high/xhigh/max; dsh: not supported; kimi_code: not supported; opencode: none/minimal/low/medium/high/xhigh/max","anyOf":[{"type":"string","enum":["none","off","minimal","low","medium","high","xhigh","max","ultra"]},{"type":"null"}]},"modelBilling":{"description":"Who pays for model calls; switching restarts the agent's engine in place","type":"string","enum":["platform","account"]},"budget":{"description":"Change the spend cap (must be strictly above consumed cost) or null to remove it — removal is one-way","anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"limit"},"max_list_cost":{"type":"object","properties":{"amount":{"type":"string","minLength":1,"maxLength":15,"description":"Whole US cents as an integer decimal string, e.g. \"125\" for $1.25"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]}},"required":["type","max_list_cost"]},{"type":"null"}]}}},"AddSessionResource":{"$schema":"http://json-schema.org/draft-07/schema#","oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1,"maxLength":128},"mount_path":{"anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},"required":["type","file_id"]},{"type":"object","properties":{"type":{"type":"string","const":"github_repository"},"url":{"type":"string","minLength":1,"maxLength":2048},"authorization_token":{"type":"string","minLength":1,"maxLength":1024},"checkout":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"branch"},"name":{"type":"string","minLength":1,"maxLength":255}},"required":["type","name"]},{"type":"object","properties":{"type":{"type":"string","const":"commit"},"sha":{"type":"string","minLength":7,"maxLength":64}},"required":["type","sha"]}]},{"type":"null"}]},"mount_path":{"anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},"required":["type","url"]}]},"UpdateSessionResource":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"authorization_token":{"type":"string","minLength":1,"maxLength":1024}},"required":["authorization_token"]},"PutPrompt":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"prompt":{"type":"string","maxLength":100000}},"required":["prompt"]},"PutSecret":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":10000},"description":{"type":"string","maxLength":500}},"required":["value"]},"PutModelSubscription":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"credential":{"type":"string","minLength":1,"maxLength":100000},"label":{"type":"string","maxLength":60}},"required":["credential"]},"PatchModelSubscription":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"useForNewAgents":{"type":"boolean"},"label":{"type":"string","maxLength":60}}},"CreateUniverse":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"slug":{"type":"string","minLength":3,"maxLength":40,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"name":{"type":"string","maxLength":80}},"required":["slug"]},"CreateRoutine":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"description":{"type":"string","maxLength":2048},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":512}},"target":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"new_session"},"agent":{"type":"string","minLength":1},"environment_id":{"type":"string","minLength":1},"vault_ids":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1}}},"required":["type","agent"]},{"type":"object","properties":{"type":{"type":"string","const":"session"},"session_id":{"type":"string","minLength":1}},"required":["type","session_id"]}]},"initial_events":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"user.message"},"content":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"base64"},"media_type":{"type":"string","minLength":1},"data":{"type":"string","minLength":1}},"required":["type","media_type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"url"},"url":{"type":"string","minLength":1}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1}},"required":["type","file_id"],"additionalProperties":false}]}},"required":["type","source"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"document"},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"base64"},"media_type":{"type":"string","minLength":1},"data":{"type":"string","minLength":1}},"required":["type","media_type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"media_type":{"default":"text/plain","type":"string","const":"text/plain"},"data":{"type":"string","minLength":1}},"required":["type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"url"},"url":{"type":"string","minLength":1}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1}},"required":["type","file_id"],"additionalProperties":false}]},"title":{"type":["string","null"]},"context":{"type":["string","null"]}},"required":["type","source"],"additionalProperties":false}]}}},"required":["type","content"],"additionalProperties":false}},"schedule":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"cron"},"expression":{"type":"string","minLength":1,"maxLength":256},"timezone":{"type":"string","minLength":1}},"required":["type","expression","timezone"]},{"type":"null"}]},"budget":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"limit"},"max_list_cost":{"type":"object","properties":{"amount":{"type":"string","minLength":1,"maxLength":15,"description":"Whole US cents as an integer decimal string, e.g. \"125\" for $1.25"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]}},"required":["type","max_list_cost"]},{"type":"null"}]}},"required":["name","target","initial_events"]},"PatchRoutine":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"description":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}]}},"target":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"new_session"},"agent":{"type":"string","minLength":1},"environment_id":{"type":"string","minLength":1},"vault_ids":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1}}},"required":["type","agent"]},{"type":"object","properties":{"type":{"type":"string","const":"session"},"session_id":{"type":"string","minLength":1}},"required":["type","session_id"]}]},"initial_events":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"user.message"},"content":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"base64"},"media_type":{"type":"string","minLength":1},"data":{"type":"string","minLength":1}},"required":["type","media_type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"url"},"url":{"type":"string","minLength":1}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1}},"required":["type","file_id"],"additionalProperties":false}]}},"required":["type","source"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"document"},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"base64"},"media_type":{"type":"string","minLength":1},"data":{"type":"string","minLength":1}},"required":["type","media_type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"media_type":{"default":"text/plain","type":"string","const":"text/plain"},"data":{"type":"string","minLength":1}},"required":["type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"url"},"url":{"type":"string","minLength":1}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1}},"required":["type","file_id"],"additionalProperties":false}]},"title":{"type":["string","null"]},"context":{"type":["string","null"]}},"required":["type","source"],"additionalProperties":false}]}}},"required":["type","content"],"additionalProperties":false}},"schedule":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"cron"},"expression":{"type":"string","minLength":1,"maxLength":256},"timezone":{"type":"string","minLength":1}},"required":["type","expression","timezone"]},{"type":"null"}]},"budget":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"limit"},"max_list_cost":{"type":"object","properties":{"amount":{"type":"string","minLength":1,"maxLength":15,"description":"Whole US cents as an integer decimal string, e.g. \"125\" for $1.25"},"currency":{"type":"string","const":"USD"}},"required":["amount","currency"]}},"required":["type","max_list_cost"]},{"type":"null"}]}}},"CreateWebhookEndpoint":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"events":{"minItems":1,"maxItems":32,"type":"array","items":{"type":"string","minLength":1}}},"required":["url","events"]},"PatchWebhookEndpoint":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"events":{"minItems":1,"maxItems":32,"type":"array","items":{"type":"string","minLength":1}},"status":{"type":"string","enum":["active","disabled"]}}},"SendMessages":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"parts":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"text"},"text":{"default":"","type":"string"},"stream_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"stream_index":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["index","type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"reasoning"},"text":{"default":"","type":"string"},"redacted":{"default":false,"type":"boolean"},"stream_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"stream_index":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["index","type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"tool_call"},"call_id":{"type":"string"},"tool_name":{"type":"string"},"args":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"args_partial":{"type":["string","null"]}},"required":["index","type","call_id","tool_name"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"tool_result"},"call_id":{"type":"string"},"tool_name":{"type":"string"},"status":{"default":"ok","type":"string","enum":["ok","error"]},"result":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["index","type","call_id","tool_name"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"file"},"name":{"type":"string"},"media_type":{"type":"string"},"uri":{"type":["string","null"]},"data":{"type":["string","null"]},"size_bytes":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["index","type","name","media_type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"image"},"media_type":{"type":"string"},"uri":{"type":["string","null"]},"data":{"type":["string","null"]},"alt":{"type":["string","null"]},"width":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["index","type","media_type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"video"},"media_type":{"type":"string"},"uri":{"type":["string","null"]},"data":{"type":["string","null"]},"alt":{"type":["string","null"]},"width":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"duration_ms":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"size_bytes":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"thumbnail_uri":{"type":["string","null"]}},"required":["index","type","media_type"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"status"},"level":{"type":"string","enum":["thinking","working","waiting","idle","done"]},"text":{"type":["string","null"]}},"required":["index","type","level"]},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","const":"error"},"code":{"type":"string"},"message":{"type":"string"},"retryable":{"default":false,"type":"boolean"}},"required":["index","type","code","message"]}]}}},"required":["parts"]},"SendEvents":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"events":{"minItems":1,"maxItems":50,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"user.message"},"content":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"base64"},"media_type":{"type":"string","minLength":1},"data":{"type":"string","minLength":1}},"required":["type","media_type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"url"},"url":{"type":"string","minLength":1}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1}},"required":["type","file_id"],"additionalProperties":false}]}},"required":["type","source"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"document"},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"base64"},"media_type":{"type":"string","minLength":1},"data":{"type":"string","minLength":1}},"required":["type","media_type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"text"},"media_type":{"default":"text/plain","type":"string","const":"text/plain"},"data":{"type":"string","minLength":1}},"required":["type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"url"},"url":{"type":"string","minLength":1}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"file"},"file_id":{"type":"string","minLength":1}},"required":["type","file_id"],"additionalProperties":false}]},"title":{"type":["string","null"]},"context":{"type":["string","null"]}},"required":["type","source"],"additionalProperties":false}]}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"system.message"},"content":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false}}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"user.interrupt"}},"required":["type"],"additionalProperties":false}]}}},"required":["events"],"additionalProperties":false},"SendEventsResult":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"One echo per event, in order, in the events-history shape","items":{"$ref":"#/components/schemas/Event"}}}},"Whoami":{"type":"object","required":["user","universe","scopes","auth"],"properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]}}},"universe":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"isPersonal":{"type":"boolean"}}},"scopes":{"type":"array","items":{"type":"string","enum":["read","write","admin"]}},"auth":{"type":"string","enum":["token","session"]}}},"Universe":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"isPersonal":{"type":"boolean"},"createdAt":{"type":"string","description":"ISO 8601"}}},"AgentSummary":{"type":"object","properties":{"id":{"type":"string","description":"The agent id (agent_…) — the only address"},"name":{"type":"string"},"displayName":{"type":"string"},"agentType":{"type":"string","description":"Engine: claude_code · codex · hermes · openclaw · pi · dsh · kimi_code · opencode"},"llm":{"type":"string"},"harnessVersion":{"type":["string","null"],"description":"The engine CLI version this agent's sessions run; PATCH to move to the platform's current version"},"reasoningEffort":{"type":["string","null"],"enum":["none","off","minimal","low","medium","high","xhigh","max","ultra",null],"description":"Harness-native reasoning effort; null = the harness's own default. Applies from the next provision/restart. Allowed values depend on agentType — hermes: none/minimal/low/medium/high/xhigh/max/ultra; claude_code: low/medium/high/xhigh/max; codex: none/minimal/low/medium/high/xhigh/max; openclaw: not supported; pi: off/minimal/low/medium/high/xhigh/max; dsh: not supported; kimi_code: not supported; opencode: none/minimal/low/medium/high/xhigh/max"},"capabilities":{"type":"array","items":{"type":"string","enum":["exa.search","exa.contents","tinyfish.fetch","tinyfish.browser","dataforseo.serp","gptimage.generate","rembg.remove-background","seedance.generate","mm.i2v","fish-audio.transcribe"]},"description":"The built-in capabilities this agent is granted — the exact set its sessions may execute (enforced; empty = none). Ids are listed at /docs/capabilities."},"version":{"type":"integer","description":"Bumped on every update; see expectedVersion"},"archived":{"type":"boolean"},"sessionCount":{"type":"integer"},"createdAt":{"type":"string","description":"ISO 8601"}}},"AgentDetail":{"type":"object","description":"Everything in the list item, plus configuration state.","properties":{"id":{"type":"string","description":"The agent id (agent_…) — the only address"},"name":{"type":"string"},"displayName":{"type":"string"},"agentType":{"type":"string"},"llm":{"type":"string"},"harnessVersion":{"type":["string","null"]},"reasoningEffort":{"type":["string","null"],"enum":["none","off","minimal","low","medium","high","xhigh","max","ultra",null]},"version":{"type":"integer"},"archived":{"type":"boolean"},"sessionCount":{"type":"integer"},"createdAt":{"type":"string"},"description":{"type":["string","null"]},"prompt":{"type":["string","null"],"description":"The user prompt layer"},"promptVersion":{"type":["integer","null"]},"capabilities":{"type":"array","items":{"type":"string","enum":["exa.search","exa.contents","tinyfish.fetch","tinyfish.browser","dataforseo.serp","gptimage.generate","rembg.remove-background","seedance.generate","mm.i2v","fish-audio.transcribe"]},"description":"The built-in capabilities this agent is granted — the exact set its sessions may execute (enforced; empty = none). Ids are listed at /docs/capabilities."},"mcpServers":{"$schema":"http://json-schema.org/draft-07/schema#","maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"default":"url","type":"string","const":"url"},"name":{"type":"string","minLength":1,"maxLength":255},"url":{"type":"string","format":"uri"},"tools":{"type":"object","properties":{"include":{"default":[],"maxItems":200,"type":"array","items":{"type":"string","minLength":1}},"exclude":{"default":[],"maxItems":200,"type":"array","items":{"type":"string","minLength":1}}}}},"required":["name","url"]},"description":"Declared remote MCP server references, including tool filters; runtime authentication fields are never returned"},"metadata":{"type":"object","description":"Your key-merged client metadata"},"defaultSessionId":{"type":["string","null"],"description":"The session conversation verbs target when addressed by agent id"},"universe":{"type":"string","description":"Resolved universe slug"}}},"Session":{"type":"object","properties":{"id":{"type":"string","description":"sess_… identifier"},"agentId":{"type":["string","null"],"description":"The agent id (agent_…)"},"title":{"type":["string","null"]},"status":{"type":"string","enum":["provisioning","idle","running","terminated"],"description":"provisioning = the sandbox is booting or installing the environment's packages (a turn sent meanwhile waits for it); running = a turn is in flight; terminated = archived"},"agentType":{"type":"string"},"llm":{"type":"string","description":"The model this session runs on (PATCH to change; the agent's model is unchanged)"},"reasoningEffort":{"type":["string","null"],"description":"The effective reasoning effort: this session's own setting, else the agent's, else null (the harness default)"},"modelBilling":{"type":"string","enum":["platform","account"],"description":"Who pays for model calls: platform wallet or the user's connected subscription"},"default":{"type":"boolean","description":"Is this the agent's default session"},"metadata":{"type":"object"},"budget":{"type":["object","null"],"description":"Hard spend cap, or null when the session has none. A reached budget pauses the session (402 budget_reached on new work) until the cap is raised above consumed_cost or removed — removal is one-way.","properties":{"max_list_cost":{"$ref":"#/components/schemas/MonetaryAmount"},"consumed_cost":{"$ref":"#/components/schemas/MonetaryAmount"},"reached":{"type":"boolean"},"reached_at":{"type":["string","null"],"description":"ISO 8601"}}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/SessionResource"},"description":"The files and GitHub repositories mounted into the working directory, oldest first"},"createdAt":{"type":"string","description":"ISO 8601"}}},"Routine":{"type":"object","description":"Scheduled agent execution: initial_events + a target (new_session per fire, or an existing session) bound to a cron schedule. Fires record routine runs.","properties":{"id":{"type":"string","description":"rtn_… identifier"},"name":{"type":"string"},"description":{"type":["string","null"]},"metadata":{"type":"object"},"target":{"type":"object","description":"{type:\"new_session\", agent, environment_id?, vault_ids?} — a fresh session per fire (CMA parity) · {type:\"session\", session_id} — a turn into the existing session every fire (busy target skips with session_busy_error)"},"initial_events":{"type":"array","items":{"type":"object"}},"schedule":{"type":["object","null"],"description":"5-field POSIX cron + IANA timezone, wall-clock matching, minute granularity; null = manual-run only","properties":{"type":{"type":"string","enum":["cron"]},"expression":{"type":"string"},"timezone":{"type":"string"},"last_run_at":{"type":["string","null"]},"upcoming_runs_at":{"type":"array","items":{"type":"string"},"description":"≤5 upcoming fire times; empty once archived"}}},"budget":{"type":["object","null"],"description":"Per-run cap (RFC-0080 shape): copied onto each new session (mode new_session) or granted as a per-fire delta allowance consumed+budget (mode session). Clearable."},"status":{"type":"string","enum":["active","paused"]},"paused_reason":{"type":["object","null"],"description":"{type:\"manual\"} | {type:\"error\", error:{type}} — non-null exactly when paused"},"archived_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"RoutineRun":{"type":"object","description":"One fire attempt. Exactly one of session_id / error is non-null.","properties":{"id":{"type":"string","description":"rrun_… identifier"},"routine_id":{"type":"string"},"trigger_context":{"type":"object","description":"{type:\"schedule\", scheduled_at} | {type:\"manual\"}"},"session_id":{"type":["string","null"]},"error":{"type":["object","null"],"description":"{type, message}. Types: agent_archived_error · agent_not_found_error · session_archived_error · session_not_found_error · session_busy_error · environment_archived_error · environment_not_found_error · vault_not_found_error · insufficient_credits_error · rate_limited_error · run_rejected_error · unknown_error. Unrecoverable types auto-pause the routine; transient ones (credits, rate limit, busy) leave it active for the next occurrence."},"agent":{"type":"object","description":"Resolved agent reference at fire time"},"created_at":{"type":"string"}}},"WebhookEndpoint":{"type":"object","description":"Outbound webhook endpoint. Deliveries carry x-asteroids-event/-delivery/-timestamp/-signature (v1=hmac-sha256(secret, \"<ts>.<body>\")), retry 3× (0s/5s/30s), and sustained failure disables (PATCH status:active re-enables). Payloads are thin {id, type, created_at, data:{type, id}} — fetch the resource, dedupe on the event id.","properties":{"id":{"type":"string","description":"whep_… identifier"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"failure_count":{"type":"integer"},"created_at":{"type":"string"},"secret":{"type":"string","description":"whsec_… — present ONLY in the create response"}}},"MonetaryAmount":{"type":"object","description":"Whole US cents as an integer decimal string — \"125\" is $1.25","properties":{"amount":{"type":"string"},"currency":{"type":"string","enum":["USD"]}}},"Event":{"type":"object","description":"One session event — identical on the stream and in history. Core fields below; the payload varies by type (agent.message carries messageId/parts/text; agent.reasoning/tool_use/tool_result carry part; session.status_idle carries stop_reason; session.error carries error; user.interrupt carries by).","required":["id","type","sessionId"],"additionalProperties":true,"properties":{"id":{"type":"string","description":"Stable event id — the dedupe key across stream ∪ events"},"type":{"type":"string","description":"user.message · system.message (both history only — never on the live stream; they carry `content`) · agent.message · agent.reasoning · agent.tool_use · agent.tool_result · agent.status · user.interrupt · session.status_running · session.status_idle · session.error · session.status_terminated · session.deleted"},"sessionId":{"type":"string"},"agentId":{"type":["string","null"],"description":"The agent id (agent_…)"},"at":{"type":"string","description":"ISO 8601"},"messageId":{"type":"string","description":"agent.message"},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MessagePart"},"description":"agent.message"},"text":{"type":"string","description":"agent.message — parts flattened to plain text"},"content":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"user.message / system.message — the CMA content blocks as sent (text · image · document); every image/document source is a `file` source naming a per-session copy readable through GET /files/{file_id}/content"},"part":{"$ref":"#/components/schemas/MessagePart","description":"reasoning / tool_use / tool_result / status events"},"stop_reason":{"type":"object","description":"session.status_idle — discriminate on type; never break on bare idle","properties":{"type":{"type":"string","description":"\"end_turn\" (also after an interrupt) | \"retries_exhausted\" (preceded by an exhausted session.error) | \"budget_reached\"; more reserved"}}},"error":{"type":"object","description":"session.error — the stream stays open; a session.status_idle follows once the turn is over","properties":{"type":{"type":"string","description":"e.g. \"pod_unavailable\""},"message":{"type":"string"},"retry_status":{"type":"string","description":"\"retrying\" (the turn continues) | \"exhausted\" (the turn is over)"}}},"by":{"type":"string","description":"user.interrupt — who requested the interrupt"}}},"EventsPage":{"type":"object","required":["events","cursor","hasMore"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"},"description":"Oldest-first"},"cursor":{"type":["string","null"],"description":"Pass back as ?cursor= for the next page; null when the session has no events"},"hasMore":{"type":"boolean"}}},"PromptUpdateResult":{"type":"object","properties":{"version":{"type":"integer"},"unchanged":{"type":"boolean","description":"Content identical to the active version"}}},"PromptVersion":{"type":"object","properties":{"version":{"type":"integer"},"note":{"type":["string","null"]},"createdAt":{"type":"string"},"active":{"type":"boolean"},"content":{"type":"string"}}},"SecretKey":{"type":"object","description":"Key names only — values never leave the platform.","properties":{"key":{"type":"string"},"description":{"type":"string"}}},"ModelSubscription":{"type":"object","description":"A connected consumer AI subscription (Claude Pro/Max or ChatGPT plan) powering eligible agents at $0 model usage. The credential itself is write-only.","properties":{"provider":{"type":"string","enum":["anthropic","openai"]},"label":{"type":"string"},"status":{"type":"string","enum":["connected","needs_reconnect"]},"expiresAt":{"type":["string","null"]},"lastUsedAt":{"type":["string","null"]},"useForNewAgents":{"type":"boolean"},"createdAt":{"type":"string"},"agents":{"type":"array","description":"Agents in this universe running on the subscription","items":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":["string","null"]},"name":{"type":"string"}}}}}},"Ok":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}},"InterruptResult":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["interrupting","no_turn"],"description":"no_turn = nothing in flight; otherwise user.interrupt echoes on the stream and the pod's session.status_idle follows"}}},"Skill":{"type":"object","required":["id","displayName","latestRevisionId","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"displayName":{"type":"string"},"latestRevisionId":{"type":["string","null"],"description":"What `latest` references resolve to."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SkillRevision":{"type":"object","required":["id","skillId","name","description","files","createdAt"],"properties":{"id":{"type":"string"},"skillId":{"type":"string"},"name":{"type":"string","description":"Frontmatter name — the skill's identity name."},"description":{"type":"string"},"files":{"type":"array","items":{"type":"object","required":["path","size","sha256","executable"],"properties":{"path":{"type":"string"},"size":{"type":"integer"},"sha256":{"type":"string"},"executable":{"type":"boolean"}}}},"createdAt":{"type":"string","format":"date-time"}}},"ChannelMessagePart":{"oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"const":"text"},"text":{"type":"string"}}},{"type":"object","required":["type","text"],"properties":{"type":{"const":"markdown"},"text":{"type":"string"}}},{"type":"object","required":["type","platform","payload"],"properties":{"type":{"const":"raw"},"platform":{"type":"string"},"payload":{"type":"string","description":"Platform-native payload, JSON-encoded"}}}]},"CreateChannelApp":{"type":"object","required":["platform","label","credentials"],"properties":{"platform":{"type":"string","enum":["telegram","slack","discord","whatsapp","imessage"]},"label":{"type":"string","maxLength":120},"credentials":{"type":"object","additionalProperties":{"type":"string"},"description":"Write-only. Required keys per platform — telegram: bot_token · discord: bot_token · slack: bot_token, signing_secret · whatsapp: access_token, phone_number_id, app_secret · imessage (coming soon — answers 501 coming_soon today): api_key, phone_number, webhook_secret"}}},"PatchChannelApp":{"type":"object","properties":{"label":{"type":"string","maxLength":120},"credentials":{"type":"object","additionalProperties":{"type":"string"},"description":"Full replacement bag; rotation re-runs the platform registration"}}},"ChannelApp":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["telegram","slack","discord","whatsapp","imessage"]},"label":{"type":"string"},"status":{"type":"string"},"credential_keys":{"type":"array","items":{"type":"string"},"description":"Key names only — values are write-only"},"created_at":{"type":"string","format":"date-time"},"setup":{"type":"object","additionalProperties":{"type":"string"},"description":"Steps the platform cannot automate (per-app webhook_url / verify_token / events_url / invite_url)"}}},"CreateChannelConnection":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","enum":["telegram","slack","discord","whatsapp","imessage","loopback"]},"label":{"type":"string","maxLength":120},"metadata":{"type":"object","description":"Echoed on channel.connected and the callback redirect"},"destination":{"type":"object","properties":{"session":{"type":"string"}},"description":"Pre-bind: the claimed surface talks to this session"},"app":{"type":"string","description":"BYO ChannelApp id — the connect ceremony runs on your bot/number"},"invite_user":{"type":"string","description":"Slack only: user id to invite into the created channel"},"callback_url":{"type":"string","description":"Link-flow platforms only: the hosted connect page redirects here after the claim with connection_id, status, and metadata query params"}}},"ChannelConnection":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string"},"channel_id":{"type":"string","nullable":true},"label":{"type":"string"},"status":{"type":"string","enum":["PENDING","CONNECTED","DISCONNECTED"]},"bound_session":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"label":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"connect":{"type":"object","description":"PENDING only: the end-user ceremony (url, and for code flows phone + code)","properties":{"url":{"type":"string"},"phone":{"type":"string"},"code":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}},"CreateChannelBinding":{"type":"object","required":["connection_id","thread_id","destination"],"properties":{"connection_id":{"type":"string"},"thread_id":{"type":"string","description":"The one thread this rule routes. Connection-level routing is a single slot — set it via PUT /connections/{id}/binding"},"destination":{"type":"object","description":"Exactly one of webhook (endpoint id) or session (session id)","properties":{"webhook":{"type":"string"},"session":{"type":"string"}}},"route_key":{"type":"string","maxLength":60}}},"ChannelBinding":{"type":"object","properties":{"id":{"type":"string"},"connection_id":{"type":"string"},"thread_id":{"type":"string","nullable":true},"destination":{"type":"object","description":"Exactly one of webhook (endpoint id) or session (session id)","properties":{"webhook":{"type":"string"},"session":{"type":"string"}}},"is_default":{"type":"boolean"},"status":{"type":"string"},"route_key":{"type":"string"}}},"CreateChannelWebhook":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"https (http allowed for localhost only)"},"events":{"type":"array","items":{"type":"string"},"description":"Default [\"message.received\"]"}}},"ChannelWebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"secret":{"type":"string","description":"whsec_ HMAC secret — returned on create only"}}},"PostChannelMessage":{"type":"object","required":["parts"],"properties":{"parts":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ChannelMessagePart"}},"display_name":{"type":"string","maxLength":80},"done":{"type":"boolean","description":"Clears the working marker (✅) for the replied-to message"}}},"PostChannelDelivery":{"type":"object","required":["destination","parts"],"properties":{"destination":{"type":"object","description":"Exactly one of webhook (endpoint id) or session (session id)","properties":{"webhook":{"type":"string"},"session":{"type":"string"}}},"parts":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ChannelMessagePart"}},"display_name":{"type":"string","maxLength":80}}},"ChannelCapabilities":{"type":"object","properties":{"connection_id":{"type":"string"},"platform":{"type":"string"},"capabilities":{"type":"object","additionalProperties":{"type":"boolean"},"description":"threads · reactions · markers · proactive · markdown · modals · ephemeral · streaming"}}},"File":{"type":"object","required":["type","id","created_at","filename","mime_type","size_bytes","downloadable","expires_at"],"properties":{"type":{"type":"string","enum":["file"]},"id":{"type":"string","description":"file_…"},"created_at":{"type":"string","format":"date-time"},"filename":{"type":"string"},"mime_type":{"type":"string"},"size_bytes":{"type":"integer"},"downloadable":{"type":"boolean","description":"false for uploads (write-once); true for the per-session copies minted when a file rides a message"},"expires_at":{"type":["string","null"],"format":"date-time"}}},"FileList":{"type":"object","required":["data","next_page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/File"},"description":"Newest first"},"next_page":{"type":["string","null"],"description":"Pass back as ?page= for the next page"}}},"FileDeleted":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["file_deleted"]},"id":{"type":"string"}}},"SessionResource":{"description":"A file or GitHub repository mounted into the session's working directory. `mount_path` is echoed absolute and normalized under /workspace. A file resource's `file_id` is the per-session copy (listed under GET /files?scope_id=). A repository's token is never echoed.","oneOf":[{"type":"object","required":["type","id","file_id","mount_path","created_at","updated_at"],"properties":{"type":{"type":"string","enum":["file"]},"id":{"type":"string","description":"sesrsc_…"},"file_id":{"type":"string","description":"The per-session copy (file_…), read-only at mount_path"},"mount_path":{"type":"string","description":"Absolute, under /workspace"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},{"type":"object","required":["type","id","url","mount_path","created_at","updated_at"],"properties":{"type":{"type":"string","enum":["github_repository"]},"id":{"type":"string","description":"sesrsc_…"},"url":{"type":"string","description":"https://github.com/{owner}/{repo}"},"mount_path":{"type":"string","description":"Absolute, under /workspace; the clone's root"},"checkout":{"type":"object","description":"{type:\"branch\", name} or {type:\"commit\", sha}; absent = the default branch","properties":{"type":{"type":"string","enum":["branch","commit"]},"name":{"type":"string"},"sha":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}]},"SessionResourceList":{"type":"object","required":["data","next_page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionResource"},"description":"Oldest first"},"next_page":{"type":["string","null"],"description":"Pass back as ?page= for the next page; null when `limit` was omitted or the list ended"}}},"SessionResourceDeleted":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["session_resource_deleted"]},"id":{"type":"string"}}}}},"paths":{"/whoami":{"get":{"summary":"Caller identity, resolved universe, effective scopes [read]","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Whoami"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/universes":{"get":{"summary":"List universes [read]","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["universes"],"properties":{"universes":{"type":"array","items":{"$ref":"#/components/schemas/Universe"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Create a universe [write, personal tokens only]","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUniverse"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["universe"],"properties":{"universe":{"$ref":"#/components/schemas/Universe"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/universes/{slug}":{"get":{"summary":"Universe detail [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The universe slug"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["universe"],"properties":{"universe":{"$ref":"#/components/schemas/Universe"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/agents":{"get":{"summary":"List agents in the resolved universe [read]","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["agents"],"properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentSummary"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Create an agent [write]","description":"An agent is a reusable configuration — engine, prompt, capabilities, secrets. Every field is optional: an empty body creates the default hermes agent with no built-in capabilities (capabilities are explicit opt-in; unknown ids → 400). The response's `id` (agent_…) is the agent's only address. One agent can run many sessions; creating the agent provisions nothing — the pod is provisioned by POST /v1/sessions.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgent"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/AgentDetail"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/agents/{id}":{"get":{"summary":"Agent detail [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The agent id (agent_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/AgentDetail"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"patch":{"summary":"Update displayName / capabilities / metadata [write]","description":"Omitted fields preserved; capabilities replaced whole (explicit [] revokes all; effective on the next capability call, no restart); metadata key-merged (null deletes a key); optional expectedVersion → 409 version_conflict on mismatch.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The agent id (agent_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchAgent"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/AgentDetail"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete the agent — only with zero sessions (409 agent_has_sessions) [admin]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The agent id (agent_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/agents/{id}/archive":{"post":{"summary":"Archive the agent — read-only, sessions keep running, new sessions rejected [admin]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The agent id (agent_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/AgentDetail"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/agents/{id}/prompt":{"put":{"summary":"Save the user prompt layer; applies to sessions started after the save [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The agent id (agent_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutPrompt"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptUpdateResult"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/agents/{id}/prompt/versions":{"get":{"summary":"Prompt version history [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The agent id (agent_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["versions"],"properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/PromptVersion"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/agents/{id}/secrets":{"get":{"summary":"Declared secret keys + set/unset — never values [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The agent id (agent_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["secrets"],"properties":{"secrets":{"type":"array","items":{"$ref":"#/components/schemas/SecretKey"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/agents/{id}/secrets/{key}":{"put":{"summary":"Set a declared secret's value (write-only) [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The agent id (agent_…)"},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutSecret"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Unset a secret [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The agent id (agent_…)"},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/model-subscriptions":{"get":{"summary":"List connected model subscriptions — metadata only, never credentials [read]","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["modelSubscriptions"],"properties":{"modelSubscriptions":{"type":"array","items":{"$ref":"#/components/schemas/ModelSubscription"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/model-subscriptions/{provider}":{"put":{"summary":"Connect or replace a subscription credential (write-only) [write]","description":"anthropic: the sk-ant-oat… token from `claude setup-token`. openai: the contents of ~/.codex/auth.json from `codex login`. Eligible agents can then run at $0 model usage; with useForNewAgents (default on), new eligible agents use it automatically.","security":[{"bearerAuth":[]}],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","enum":["anthropic","openai"]},"description":"anthropic = Claude subscription · openai = ChatGPT plan"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutModelSubscription"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["modelSubscription"],"properties":{"modelSubscription":{"$ref":"#/components/schemas/ModelSubscription"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"patch":{"summary":"Update useForNewAgents / label [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","enum":["anthropic","openai"]},"description":"anthropic = Claude subscription · openai = ChatGPT plan"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchModelSubscription"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["modelSubscription"],"properties":{"modelSubscription":{"$ref":"#/components/schemas/ModelSubscription"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Disconnect — affected agents keep their pointer and fail until reconnected or switched [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","enum":["anthropic","openai"]},"description":"anthropic = Claude subscription · openai = ChatGPT plan"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"affectedAgents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":["string","null"]},"name":{"type":"string"}}}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/skills":{"get":{"summary":"List skills in the resolved universe [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["skills"],"properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"nextCursor":{"type":["string","null"]}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Create a skill (uploads revision 1) [write]","description":"A skill is a universe-scoped, immutably-revisioned file bundle agents load on demand (RFC-0073). Attach it to agents via the `skills` array on create/patch.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"One zip archive or individual files. SKILL.md with `name` + `description` frontmatter must sit at the root of the single top-level directory. ≤30 MB uncompressed; zip entries keep their unix exec bit."},"displayName":{"type":"string","maxLength":255}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["skill","revision"],"properties":{"skill":{"$ref":"#/components/schemas/Skill"},"revision":{"$ref":"#/components/schemas/SkillRevision"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/skills/{skillId}":{"get":{"summary":"Skill detail [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"description":"The skill id (skill_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["skill"],"properties":{"skill":{"$ref":"#/components/schemas/Skill"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a skill and all its revisions [write]","description":"409 skill_in_use while any agent references the skill.","security":[{"bearerAuth":[]}],"parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"description":"The skill id (skill_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/skills/{skillId}/revisions":{"get":{"summary":"List a skill's revisions, newest first [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"description":"The skill id (skill_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["revisions"],"properties":{"revisions":{"type":"array","items":{"$ref":"#/components/schemas/SkillRevision"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Create a revision — a complete snapshot [write]","description":"Omitted files are not carried over. The new SKILL.md name must match the skill's name (400 name_mismatch).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"One zip archive or individual files. SKILL.md with `name` + `description` frontmatter must sit at the root of the single top-level directory. ≤30 MB uncompressed; zip entries keep their unix exec bit."},"displayName":{"type":"string","maxLength":255}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"revision":{"$ref":"#/components/schemas/SkillRevision"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/skills/{skillId}/revisions/{revisionId}":{"get":{"summary":"Skill revision detail (metadata + file manifest) [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"description":"The skill id (skill_…)"},{"name":"revisionId","in":"path","required":true,"schema":{"type":"string"},"description":"The skill revision id (skr_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"revision":{"$ref":"#/components/schemas/SkillRevision"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete one revision [write]","description":"400 last_revision for a skill's only revision; 409 revision_in_use while pinned by an agent; deleting the latest repoints latestRevisionId.","security":[{"bearerAuth":[]}],"parameters":[{"name":"skillId","in":"path","required":true,"schema":{"type":"string"},"description":"The skill id (skill_…)"},{"name":"revisionId","in":"path","required":true,"schema":{"type":"string"},"description":"The skill revision id (skr_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions":{"get":{"summary":"List sessions; ?agent= filters to one spec [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"agent","in":"query","schema":{"type":"string"},"description":"The agent id (agent_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["sessions"],"properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/Session"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Create a session — provisions the pod up front so the first turn isn't a cold boot [write]","description":"Optional llm and reasoningEffort override the agent's defaults for this session before billing selection or provisioning. A model must be current for the agent's harness; omitted or null reasoningEffort inherits the agent's setting. A non-empty initial_events list (user.message only, all-or-nothing) starts the first turn in the same call. Machine shape (vcpus/memoryMb) is per-session.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSession"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["session"],"properties":{"session":{"$ref":"#/components/schemas/Session"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions/{id}":{"get":{"summary":"Session detail — status is provisioning (sandbox booting or installing packages) | idle | running | terminated [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["session"],"properties":{"session":{"$ref":"#/components/schemas/Session"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"patch":{"summary":"Update title / metadata / model / reasoning effort / billing / budget [write]","description":"llm and reasoningEffort are session settings: they change this session only, never the agent or its other sessions, and must fit the session's harness. An idle session restarts its engine in place; a running session finishes its turn and applies the change at the next turn (the response is 200 either way). A parked session applies it at its next wake.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchSession"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["session"],"properties":{"session":{"$ref":"#/components/schemas/Session"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Permanently delete the session, its events, and its pod [write]","description":"Hard delete — the record, event history, pod, and stored context snapshots are permanently removed; GET answers 404 after. A running session is refused with 400 session_running: interrupt and wait for idle first. Works on idle and archived/terminated sessions.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions/{id}/share":{"post":{"summary":"Turn sharing on and get the share link — idempotent; {\"rotate\": true} replaces it [write]","description":"The returned URL opens the session's guest page for anyone holding it, with no account; turns sent through it bill the session's owner. Rotating kills the old URL immediately.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rotate":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["shareUrl"],"properties":{"shareUrl":{"type":"string"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Turn sharing off — the link stops working immediately [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions/{id}/archive":{"post":{"summary":"Archive the session — irreversible; blocks new events, history stays readable [write]","description":"Sets status to terminated, tears down the pod and stored context, and refuses further messages (400 session_archived); the record and its events remain readable. A running session is refused with 400 session_running: interrupt and wait for idle first. Idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["session"],"properties":{"session":{"$ref":"#/components/schemas/Session"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions/{id}/messages":{"post":{"deprecated":true,"summary":"Deprecated — use POST /sessions/{id}/events [write]","description":"The legacy input shape ({parts}); accepted for one release and translated to a single user.message, then 410. Optional Idempotency-Key header dedupes retries.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessages"}}}},"responses":{"202":{"description":"Accepted — body is {}; output arrives on the stream","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions/{id}/events":{"post":{"summary":"Send events — the one input: user.message, user.interrupt, system.message [write]","description":"The conversation plane (edge-routed to the chat-proxy). Body {events: [...]} (1–50), validated all-or-nothing. A user.message carries content blocks: text, image and document with base64 / url / file sources (inline base64 ≤ 20 MiB per request; larger content goes through POST /files). A system.message (text only) must be last and follow the user.message it accompanies: privileged context for that turn and, through the agent's transcript, later turns. user.interrupt stops the in-flight turn. Every event echoes back in the history shape with a stable id; sources are echoed as file sources naming per-session copies (never base64). Optional Idempotency-Key header: a replay returns the original echo. 402 insufficient_credits / budget_reached, 503 egress_policy_failed, 400 session_archived refuse the whole request before any row is written.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEvents"}}}},"responses":{"200":{"description":"OK — one echo per event, in order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEventsResult"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"get":{"summary":"The event history — the same event objects the stream delivers [read]","description":"The session's history, one event per message: user.message and system.message (with content), agent.message (with parts), user.interrupt, and the turn marks session.status_running, session.status_idle (stop_reason.type is end_turn, retries_exhausted or budget_reached) and session.error. agent.reasoning, agent.tool_use, agent.tool_result and agent.status appear on the live stream only, not in history. Oldest-first with an opaque numeric cursor. Reconnect = open the stream, list events, dedupe by event id. types[] filters (e.g. types[]=user.message&types[]=agent.message is the transcript view).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":500}},{"name":"types[]","in":"query","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsPage"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions/{id}/stream":{"get":{"summary":"The standing event stream (SSE) [read]","description":"text/event-stream, live-only, stays open across turns. Events: agent.message, agent.reasoning, agent.tool_use, agent.tool_result, agent.status, session.status_running, session.status_idle (carries stop_reason — never break on bare idle), session.error (the stream stays open; an idle follows), user.interrupt, session.status_terminated (terminal), session.deleted (terminal). User messages are not sent on the live stream — they appear in the event history only. Reconnect = reopen + list events + dedupe by event id.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"responses":{"200":{"description":"SSE stream","content":{"text/event-stream":{}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions/{id}/interrupt":{"post":{"summary":"Abort the in-flight turn [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterruptResult"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/routines":{"get":{"summary":"List routines [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"},"description":"1–500, default 50"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Routine"}},"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Create a routine — scheduled agent execution [write]","description":"initial_events (1–50 user.message events) are delivered on every fire. target picks the mode: new_session creates a fresh session per run; session sends the turn into an existing session (busy target → failed run session_busy_error). schedule is a 5-field POSIX cron with an IANA timezone; omit it for a manual-run-only routine. budget bounds each run separately.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRoutine"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["routine"],"properties":{"routine":{"$ref":"#/components/schemas/Routine"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/routines/{id}":{"get":{"summary":"Routine detail [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The routine id (rtn_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["routine"],"properties":{"routine":{"$ref":"#/components/schemas/Routine"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"patch":{"summary":"Update a routine — omit preserves; null clears schedule/budget [write]","description":"initial_events is a full replacement; metadata is key-patched (null deletes a key); name and target cannot be cleared. Archived routines are immutable (409).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The routine id (rtn_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchRoutine"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["routine"],"properties":{"routine":{"$ref":"#/components/schemas/Routine"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/routines/{id}/pause":{"post":{"summary":"Pause — suppress scheduled fires; manual runs still work [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The routine id (rtn_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["routine"],"properties":{"routine":{"$ref":"#/components/schemas/Routine"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/routines/{id}/unpause":{"post":{"summary":"Unpause — resumes from the NEXT occurrence; missed fires are never backfilled [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The routine id (rtn_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["routine"],"properties":{"routine":{"$ref":"#/components/schemas/Routine"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/routines/{id}/archive":{"post":{"summary":"Archive — terminal; the schedule stops and the routine becomes immutable [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The routine id (rtn_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["routine"],"properties":{"routine":{"$ref":"#/components/schemas/Routine"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/routines/{id}/run":{"post":{"summary":"Manual run — fire now, outside the schedule; works while paused [write]","description":"Records trigger_context {type:\"manual\"}; manual runs emit no routine_run webhooks.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The routine id (rtn_…)"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["run"],"properties":{"run":{"$ref":"#/components/schemas/RoutineRun"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/routine-runs":{"get":{"summary":"List routine runs — every fire attempt [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"routine","in":"query","schema":{"type":"string"},"description":"Filter to one routine (rtn_…)"},{"name":"has_error","in":"query","schema":{"type":"boolean"},"description":"true = failed runs, false = runs with a session"},{"name":"trigger_type","in":"query","schema":{"type":"string","enum":["schedule","manual"]}},{"name":"created_at[gte]","in":"query","schema":{"type":"string"},"description":"Also gt / lt / lte"},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RoutineRun"}},"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/routine-runs/{id}":{"get":{"summary":"Routine run detail [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The run id (rrun_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["run"],"properties":{"run":{"$ref":"#/components/schemas/RoutineRun"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/webhooks":{"get":{"summary":"List webhook endpoints [read]","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Register a webhook endpoint — the whsec_ secret appears only in this response [write]","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpoint"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["webhook"],"properties":{"webhook":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/webhooks/{id}":{"get":{"summary":"Webhook endpoint detail [read]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The webhook endpoint id (whep_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["webhook"],"properties":{"webhook":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"patch":{"summary":"Update url/events, or status:active to re-enable a disabled endpoint [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The webhook endpoint id (whep_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchWebhookEndpoint"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["webhook"],"properties":{"webhook":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a webhook endpoint [write]","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The webhook endpoint id (whep_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/apps":{"get":{"summary":"List BYO channel apps — credentials masked [read]","tags":["channels"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["apps"],"properties":{"apps":{"type":"array","items":{"$ref":"#/components/schemas/ChannelApp"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Register your own bot/number as a channel app [write]","description":"Credentials are proven against the platform where an API exists, stored encrypted, and write-only from then on. The response's setup object carries the steps the platform cannot automate (webhook URLs to paste, invite links).","tags":["channels"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChannelApp"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelApp"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/apps/{id}":{"get":{"summary":"Channel app detail — credentials masked [read]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The channel app id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelApp"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"patch":{"summary":"Rename or rotate credentials (rotation re-runs registration) [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The channel app id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchChannelApp"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelApp"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete the channel app [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The channel app id"}],"responses":{"204":{"description":"Deleted"},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/connections":{"get":{"summary":"List connections with their bound session [read]","tags":["channels"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["connections"],"properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/ChannelConnection"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Connect a surface — link-flow platforms return a pending connect ceremony [write]","description":"telegram/imessage/whatsapp mint a connect link (deep link + code) the end user claims in-platform; slack/discord create the channel synchronously under the app identity. Pass app for BYO; callback_url (link flows) redirects the hosted connect page to you after the claim.","tags":["channels"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChannelConnection"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelConnection"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/connections/{id}":{"delete":{"summary":"Disconnect the surface [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The connection id"}],"responses":{"204":{"description":"Disconnected"},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/connections/{id}/binding":{"put":{"summary":"Set where the surface routes — a session or your webhook endpoint (single active binding) [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The connection id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["destination"],"properties":{"destination":{"type":"object","description":"Exactly one of webhook (endpoint id) or session (session id)","properties":{"webhook":{"type":"string"},"session":{"type":"string"}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"connection_id":{"type":"string"},"binding_id":{"type":"string"},"session":{"type":"string"},"webhook":{"type":"string"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/connections/{id}/capabilities":{"get":{"summary":"Declared platform capabilities — branch on these instead of guessing [read]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The connection id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelCapabilities"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/bindings":{"get":{"summary":"List bindings, optionally by connection [read]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"connection_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["bindings"],"properties":{"bindings":{"type":"array","items":{"$ref":"#/components/schemas/ChannelBinding"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Route one thread of a connection to a session or your webhook [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChannelBinding"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelBinding"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/bindings/{id}":{"delete":{"summary":"Delete the binding [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The binding id"}],"responses":{"204":{"description":"Deleted"},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/webhooks":{"get":{"summary":"List webhook endpoints [read]","tags":["channels"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/ChannelWebhookEndpoint"}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Create a webhook endpoint — HMAC-signed deliveries, 0/5/30s retries [write]","description":"Deliveries carry X-Asteroids-{Event,Delivery,Timestamp,Signature}; ~20 consecutive failures disable the endpoint. Consumers must be idempotent by delivery id.","tags":["channels"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChannelWebhook"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelWebhookEndpoint"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/webhooks/{id}":{"patch":{"summary":"Re-enable a disabled endpoint (resets failures, keeps the secret) and/or re-pick events [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The webhook endpoint id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ACTIVE"]},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelWebhookEndpoint"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete the webhook endpoint [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The webhook endpoint id"}],"responses":{"204":{"description":"Deleted"},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/threads/{id}/messages":{"post":{"summary":"Post into a thread — markdown renders natively per platform [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The thread id (from message.received or channel events)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostChannelMessage"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string"},"thread_id":{"type":"string"}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/threads/{id}/messages/{mid}/reactions/{emoji}":{"put":{"summary":"Add a reaction (platform-neutral emoji names) [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The thread id"},{"name":"mid","in":"path","required":true,"schema":{"type":"string"}},{"name":"emoji","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Reacted"},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Remove a reaction [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The thread id"},{"name":"mid","in":"path","required":true,"schema":{"type":"string"}},{"name":"emoji","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Removed"},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/deliveries":{"post":{"summary":"Proactive fan-out: post to every thread bound to a destination [write]","tags":["channels"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostChannelDelivery"}}}},"responses":{"200":{"description":"OK — per-thread results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"thread_id":{"type":"string"},"status":{"type":"string"}}}}}}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/channels/events/stream":{"get":{"summary":"SSE mirror of your webhook events — for local development [read]","tags":["channels"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"SSE stream","content":{"text/event-stream":{}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/files":{"post":{"summary":"Upload a file — universe-scoped, write-once [write]","description":"multipart/form-data with a `file` part and an optional `expires_in_seconds` (3600–7776000). 32 MiB per file (413 file_too_large). Reference the returned id from a message as `{\"type\":\"image\",\"source\":{\"type\":\"file\",\"file_id\":\"file_…\"}}` or a `document` block.","tags":["files"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"expires_in_seconds":{"type":"integer","minimum":3600,"maximum":7776000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"get":{"summary":"List files — your universe's uploads, or one session's files [read]","description":"Without `scope_id`, the universe's uploads. `scope_id=sess_…` lists that session's files: the copies minted from message content, channel attachments, and agent-stored files. `ids[]` (≤100) returns exactly those files in one page and cannot be combined with page/limit.","tags":["files"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":20}},{"name":"page","in":"query","schema":{"type":"string"},"description":"A next_page cursor"},{"name":"ids[]","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"scope_id","in":"query","schema":{"type":"string"},"description":"sess_…"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileList"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/files/{file_id}":{"get":{"summary":"File metadata [read]","tags":["files"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string"},"description":"The file id (file_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a file [write]","description":"Soft delete: the file stops resolving everywhere; sessions that already received a copy keep it.","tags":["files"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string"},"description":"The file id (file_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDeleted"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/files/{file_id}/content":{"get":{"summary":"Download a file's bytes [read]","description":"Only `downloadable` files (every session-scoped file: message copies, channel attachments, agent outputs); an upload answers 400 not_downloadable. 404 once the file has expired.","tags":["files"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string"},"description":"The file id (file_…)"}],"responses":{"200":{"description":"The bytes, with content-type and content-disposition","content":{"*/*":{}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions/{id}/resources":{"get":{"summary":"List the session's resources, oldest first [read]","description":"`limit` (1–1000) pages the list with an opaque `page` cursor; omitted lists every resource in one answer.","tags":["sessions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id (sess_…)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"page","in":"query","schema":{"type":"string"},"description":"A next_page cursor"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResourceList"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Add a file to a running session [write]","description":"Files only — a `github_repository` body answers 400 (repositories are attached at session create and stay for the session's lifetime). The file is copied read-only to `/workspace<mount_path>` before the session's next turn; `mount_path` follows the create rules (rooted under /workspace, no escape, no overlap with another resource). 400 too_many_resources past 500 per session; 400 session_archived on an archived session.","tags":["sessions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id (sess_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSessionResource"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResource"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/sessions/{id}/resources/{rid}":{"get":{"summary":"One resource [read]","tags":["sessions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id (sess_…)"},{"name":"rid","in":"path","required":true,"schema":{"type":"string"},"description":"The resource id (sesrsc_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResource"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"summary":"Rotate a repository's token [write]","description":"Only `github_repository` resources accept an update, and the token is the only field: it is re-encrypted and the session's egress policy is recompiled and pushed to its live pod — nothing changes inside the sandbox. A file answers 400. A token that conflicts with another secret's Authorization header on github.com answers 400 egress_header_conflict.","tags":["sessions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id (sess_…)"},{"name":"rid","in":"path","required":true,"schema":{"type":"string"},"description":"The resource id (sesrsc_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSessionResource"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResource"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"summary":"Remove a file from the session [write]","description":"Files only — the resource and its per-session copy are deleted and the pod unlinks the file before the session's next turn. A `github_repository` answers 400: repositories cannot be removed mid-session.","tags":["sessions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The session id (sess_…)"},{"name":"rid","in":"path","required":true,"schema":{"type":"string"},"description":"The resource id (sesrsc_…)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResourceDeleted"}}}},"default":{"description":"Error — { error: { code, message } }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}}}