{ "openapi": "3.1.0", "info": { "title": "Context Managed Agents API", "version": "2026-04-01", "description": "The Managed Agents endpoints served at /v1. Requests authenticate with a Task API key (tsk_...) in x-api-key." }, "servers": [ { "url": "https://api.context.ai", "description": "Replace with your deployment's host" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "Error": { "type": "object", "required": [ "type", "error", "request_id" ], "properties": { "type": { "const": "error" }, "error": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string" }, "message": { "type": "string" } } }, "request_id": { "type": "string" } } }, "Agent": { "type": "object", "properties": { "id": { "type": "string", "description": "The agent's ID. Pass it as agent when you [create a session](/build/agent-api/sessions/create)." }, "type": { "type": "string", "description": "Always agent." }, "name": { "type": "string", "description": "The agent's name, as shown in the app." }, "description": { "type": [ "string", "null" ], "description": "The agent's purpose. null when the agent has no description." }, "model": { "type": "object", "description": "The agent's model, as an object with one field, id. The ID is default when the agent uses your deployment's default model." }, "system": { "type": [ "string", "null" ], "description": "The agent's instructions. They are returned only to a personal key with agents:write whose owner created the agent and still owns it. Any other key gets null. If the agent has no instructions, that key gets \"\"." }, "tools": { "type": "array", "items": { "type": "object" }, "description": "The agent's built-in tools, as one agent_toolset_20260401 entry that lists all eight tools with their enabled and permission_policy. The list is empty when every built-in tool is off." }, "skills": { "type": "array", "items": { "type": "object" }, "description": "The agent's skills, each {type, skill_id, version}. A built-in skill has type anthropic and its slug as skill_id. A custom skill has type custom and its skill ID. version is always latest." }, "created_at": { "type": "string", "description": "When the agent was created, as an RFC 3339 timestamp." }, "updated_at": { "type": "string", "description": "When the agent was last changed, as an RFC 3339 timestamp." } }, "example": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "archived_at": null, "created_at": "2026-10-21T01:35:05.337Z", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "metadata": {}, "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [ { "type": "anthropic", "skill_id": "xlsx", "version": "latest" } ], "system": null, "tools": [ { "type": "agent_toolset_20260401", "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "configs": [ { "type": "bash", "name": "bash", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "edit", "name": "edit", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "read", "name": "read", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "write", "name": "write", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "glob", "name": "glob", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "grep", "name": "grep", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "web_fetch", "name": "web_fetch", "enabled": true, "permission_policy": { "type": "always_ask" }, "url_sources": null }, { "type": "web_search", "name": "web_search", "enabled": false, "permission_policy": { "type": "always_ask" } } ] } ], "type": "agent", "updated_at": "2026-10-21T01:35:05.337Z", "version": 1 }, "description": "Some fields always hold the same value: version is 1, mcp_servers is empty, metadata is {} (the workspace_id sent on create is not stored), multiagent and archived_at are null, and execution_identity is {type: \"service_account\"}." }, "Environment": { "type": "object", "properties": { "id": { "type": "string", "description": "Always env_default." }, "type": { "type": "string", "description": "Always environment." }, "name": { "type": "string", "description": "Always default." }, "description": { "type": "string", "description": "A one-line description." }, "config": { "type": "object", "description": "An object whose type is cloud. It also holds networking, always unrestricted, and packages, always empty." }, "created_at": { "type": "string", "description": "When the environment was created, as an RFC 3339 timestamp." }, "updated_at": { "type": "string", "description": "When the environment last changed, as an RFC 3339 timestamp." } }, "example": { "id": "env_default", "archived_at": null, "config": { "type": "cloud", "networking": { "type": "unrestricted" }, "packages": { "apt": [], "cargo": [], "gem": [], "go": [], "npm": [], "pip": [] } }, "created_at": "2026-10-14T00:00:00.000Z", "description": "The platform's own runtime. Every session runs here.", "metadata": {}, "name": "default", "type": "environment", "updated_at": "2026-10-14T00:00:00.000Z" }, "description": "Some fields always hold the same value: metadata is {} and archived_at is null. Treat the following values on env_default as placeholders, because they don't describe the real environment. Its description is a fixed string. Its config always reports networking: unrestricted and empty packages. If a self-hosted install restricts sandbox network access in the KOTS Admin Console, config doesn't show that yet." }, "Session": { "type": "object", "properties": { "id": { "type": "string", "description": "The session's ID, a UUID. It is also the task's ID in the app." }, "type": { "type": "string", "description": "Always session." }, "status": { "type": "string", "description": "The session's status. One of idle, running or terminated. See [Status](#status)." }, "title": { "type": [ "string", "null" ], "description": "The session's title. The maximum length is 280 characters." }, "agent": { "type": "object", "description": "The agent the session runs, as in [Agents](/build/agent-api/agents/overview) without its timestamps and metadata." }, "environment_id": { "type": "string", "description": "Where the session runs: env_default. See [Environments](/build/agent-api/environments/overview)." }, "resources": { "type": "array", "items": { "type": "object" }, "description": "The files attached when the session was created, each {id, type: \"file\", file_id, mount_path, created_at, updated_at}. If you sent a mount_path, this is the file's absolute path on the agent's disk. Otherwise it is inputs/, in the session's inputs/ folder. id equals file_id." }, "usage": { "type": "object", "description": "The totals for the whole session, subagents included: input_tokens, output_tokens, cache_read_input_tokens, cache_creation, active_seconds and list_cost." }, "usage.cache_creation": { "type": "object", "description": "Cache-write tokens, as {ephemeral_5m_input_tokens, ephemeral_1h_input_tokens}. ephemeral_1h_input_tokens is always 0, because every cache write counts as a 5-minute write." }, "usage.active_seconds": { "type": "number", "description": "The seconds the session spent working, to the millisecond. Time spent waiting for a tool approval isn't counted. While a turn runs, the value grows on every read." }, "usage.list_cost": { "type": [ "object", "null" ], "description": "The session's cost at list price, as {amount, currency: \"USD\"}. amount is a whole number of cents, as a string. It covers model calls plus web search, image search and media generation, priced for the session's owner. See the list below the table for when it is null." }, "created_at": { "type": "string", "description": "When the session was created, as an RFC 3339 timestamp." }, "updated_at": { "type": "string", "description": "When the session last changed, as an RFC 3339 timestamp." }, "archived_at": { "type": [ "string", "null" ], "description": "For an archived session, the time it last changed, as an RFC 3339 timestamp. That is when it was archived, unless it was renamed after, which sets it to the time of the rename. null for a session that isn't archived." } }, "example": { "id": "dd13d728-93e3-440a-874c-4efeb58c97e0", "agent": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [], "system": null, "tools": [], "type": "agent", "version": 1 }, "archived_at": null, "budget": null, "created_at": "2026-10-21T01:42:16.079Z", "environment_id": "env_default", "metadata": {}, "outcome_evaluations": [], "resources": [ { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "file_id": "329409ba-f288-4b44-9c73-14a18150edee", "mount_path": "inputs/cities.csv", "type": "file", "updated_at": "2026-10-21T01:41:11.028Z" } ], "stats": {}, "status": "idle", "title": "Quarterly city report", "type": "session", "updated_at": "2026-10-21T01:42:29.719Z", "usage": { "input_tokens": 12, "output_tokens": 318, "cache_read_input_tokens": 133496, "cache_creation": { "ephemeral_5m_input_tokens": 2210, "ephemeral_1h_input_tokens": 0 }, "active_seconds": 7.331, "list_cost": { "amount": "6", "currency": "USD" } }, "vault_ids": [] }, "description": "Some fields always hold the same value: budget is null, metadata and stats are {}, and outcome_evaluations and vault_ids are empty." }, "Event": { "type": "object", "properties": { "id": { "type": "string", "description": "The event's ID, in the form sevt__." }, "type": { "type": "string", "description": "One of the types below." }, "processed_at": { "type": [ "string", "null" ], "description": "When the event was processed, as an RFC 3339 timestamp. It is null only on send receipts." } }, "example": { "type": "agent.message", "id": "sevt_40_0", "processed_at": "2026-10-21T01:42:24.003Z", "content": [ { "type": "text", "text": "The output is `first`." } ] } }, "File": { "type": "object", "properties": { "id": { "type": "string", "description": "The file's ID. An uploaded file's ID is a UUID. A file a session produced has an ID that starts with sesnfile_. Treat both as opaque." }, "type": { "type": "string", "description": "Always file." }, "filename": { "type": "string", "description": "The name sent with the upload. For a file a session produced, this is its path in the session's output folder, such as charts/q3.csv." }, "mime_type": { "type": "string", "description": "The media type sent with the upload, or application/octet-stream if none was sent." }, "size_bytes": { "type": "integer", "description": "The size in bytes, or 0 if the size wasn't recorded." }, "created_at": { "type": "string", "description": "When the file was uploaded or written, as an RFC 3339 timestamp." }, "downloadable": { "type": "boolean", "description": "Always true." }, "scope": { "type": "object", "description": "The session that produced the file, as {type: \"session\", id}, where id is the session's ID. Uploaded files have no scope field." } }, "example": { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "filename": "cities.csv", "mime_type": "text/csv", "size_bytes": 46, "type": "file", "downloadable": true } }, "Skill": { "type": "object", "properties": { "id": { "type": "string", "description": "The skill's ID. A built-in skill's ID is its slug, such as pptx." }, "type": { "type": "string", "description": "Always skill." }, "display_name": { "type": "string", "description": "The skill's name, the same as the name in its SKILL.md." }, "source": { "type": "object", "description": "Who made the skill. source.type is custom for a skill a user uploaded, or anthropic for one of your deployment's built-in skills." }, "latest_version_id": { "type": "string", "description": "The ID of the skill's newest version. An agent always runs a skill's newest version." }, "created_at": { "type": "string", "description": "When the skill was created, as an RFC 3339 timestamp." }, "updated_at": { "type": "string", "description": "When the skill last changed, as an RFC 3339 timestamp." } }, "example": { "id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e", "type": "skill", "created_at": "2026-10-27T15:02:11.204Z", "display_name": "pr-summary", "latest_version_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "source": { "type": "custom" }, "updated_at": "2026-10-27T15:02:11.204Z" } } } }, "tags": [ { "name": "Agents", "description": "An agent is the configured worker that a session runs. You can create and edit agents in the Context app or with this API, which follows Anthropic's Managed Agents API with the differences listed at the end of this page. An agent you create with the API appears in the Context app, and the owner of the API key owns it." }, { "name": "Environments", "description": "An environment is where a session runs. You choose one rather than create one. The one environment is env_default, which runs each session in the cloud, wherever the platform places it. Nothing about it can be configured over this API. Remote sandbox support is on the roadmap." }, { "name": "Sessions", "description": "A session is one conversation with an agent. Each session is a task in the Context app. The owner of the key that created it owns the task. A service account key can name another member as the owner with the x-context-owner-user-id or x-context-owner-user-email header. The task has the same transcript and tool permissions as a task started in the app. A session ends when you archive it, and its history stays readable. Nothing deletes a session for you: your deployment keeps it until you delete it. To remove a session and its data permanently, delete it with a key that has sessions:delete, which keys don't have by default (see [Choosing a key](/build/agent-api/choosing-a-key)). To send messages to a session and stream the agent's replies, see [Events](/build/agent-api/events/overview)." }, { "name": "Events", "description": "Everything that happens in a session is an event: your messages, the agent's replies and tool calls, and status changes. You send events to steer the session and read them from the history or a live stream. The events follow Anthropic's Managed Agents API, with the differences listed at the end of this page." }, { "name": "Files", "description": "A file is either a document you upload for an agent to read during a session, or an output an agent writes during a session. Upload a file, then attach it when you [create a session](/build/agent-api/sessions/create). Each upload is stored in the Context app, in the Drive of the user who owns the API key." }, { "name": "Skills", "description": "A skill is a folder of instructions and files that an agent loads when a task needs it. Its SKILL.md file names the skill and says when to use it. With this API you can upload a skill, list the skills your key can read and download any version." } ], "paths": { "/v1/agents": { "get": { "operationId": "agents_list", "summary": "List agents", "description": "Lists the agents an API key can run, one page at a time. A personal key lists the agents its owner can run, sorted by updated_at, newest first. This is the same list\nthe agent picker in the Context app shows. A service account key lists every agent in the organization, sorted\nby created_at, newest first. If the key is limited to specific agents (its **Agent scope**), the result\nincludes only those. The list never includes archived agents.\n\nThe system field is null unless the key is a personal key with agents:write whose owner created the agent.\nA service account key always gets null.", "tags": [ "Agents" ], "x-capability": "tasks:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "The maximum number of agents to return. Must be between 1 and 100. A personal key returns at most 50 agents per page, even when limit is higher." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_page value from the previous response. Leave it out to get the first page." }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Not supported. Omit it or send false. Any other value returns 400." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "archived_at": null, "created_at": "2026-10-21T01:35:05.337Z", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "metadata": {}, "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [ { "type": "anthropic", "skill_id": "xlsx", "version": "latest" } ], "system": null, "tools": [ { "type": "agent_toolset_20260401", "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "configs": [ { "type": "bash", "name": "bash", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "edit", "name": "edit", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "read", "name": "read", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "write", "name": "write", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "glob", "name": "glob", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "grep", "name": "grep", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "web_fetch", "name": "web_fetch", "enabled": true, "permission_policy": { "type": "always_ask" }, "url_sources": null }, { "type": "web_search", "name": "web_search", "enabled": false, "permission_policy": { "type": "always_ask" } } ] } ], "type": "agent", "updated_at": "2026-10-21T01:35:05.337Z", "version": 1 } ], "next_page": null } } } }, "400": { "description": "invalid_request_error: limit is outside 1 to 100. Send a value from 1 to 100. page is not a next_page value from this API. Send the next_page value from the previous response, unchanged. include_archived is any value other than false. Omit it. The request sends a created_at[*] filter (created_at[gte] or created_at[lte]). Remove it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "agents_create", "summary": "Create an agent", "description": "Creates an agent that the key's owner owns. The API applies the same checks and defaults as creating an agent in the Context app. You need permission to\ncreate agents in the organization, and the key must have no **Agent scope** (no list of specific agents). If the\nrequest fails, no agent is created.\n\nThe agent goes in the workspace named by metadata.workspace_id. Without it, the agent goes in your oldest\nshared (not private) workspace that you can work in, or in no workspace if there is none.", "tags": [ "Agents" ], "x-capability": "agents:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "archived_at": null, "created_at": "2026-10-21T01:35:05.337Z", "description": null, "execution_identity": { "type": "service_account" }, "mcp_servers": [], "metadata": {}, "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [ { "type": "anthropic", "skill_id": "xlsx", "version": "latest" } ], "system": "Answer from the attached files and cite them.", "tools": [ { "type": "agent_toolset_20260401", "default_config": { "enabled": true, "permission_policy": { "type": "always_allow" } }, "configs": [ { "type": "bash", "name": "bash", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "edit", "name": "edit", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "read", "name": "read", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "write", "name": "write", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "glob", "name": "glob", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "grep", "name": "grep", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "web_fetch", "name": "web_fetch", "enabled": true, "permission_policy": { "type": "always_allow" }, "url_sources": null }, { "type": "web_search", "name": "web_search", "enabled": false, "permission_policy": { "type": "always_ask" } } ] } ], "type": "agent", "updated_at": "2026-10-21T01:35:05.337Z", "version": 1 } } } }, "400": { "description": "invalid_request_error: name is empty or over 100 characters, or model is missing. Send a name of 1 to 100 characters and a model. model is not a model your deployment runs, or it sets effort, inference_geo or speed. Send default or a model ID only. metadata has a key other than workspace_id. Remove the other keys. The body sends version, a non-empty mcp_servers, a multiagent that is not null, an execution_identity other than {type: \"service_account\"}, or a field this API does not take. Remove it. tools has a custom tool, an mcp_toolset, a second agent_toolset_20260401 or a tool named twice. Send one built-in toolset that names each tool once. A permission_policy is auto. Use always_allow or always_ask. edit and write have different settings. Give them the same enabled and permission_policy, because the app has one setting for both. web_search is enabled, or named without enabled: false. Leave it out or send enabled: false. A web_fetch or web_search config sets domain lists, max_content_tokens, url_sources or user_location. Send only name, enabled and permission_policy. A skill is listed twice, has a version other than latest, or names a built-in slug your deployment doesn't have. List each skill once, by a built-in slug your deployment has or by a custom skill ID from [List skills](/build/agent-api/skills/list).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: This key lacks agents:write, is not a personal key, or has an **Agent scope**. Use a personal key with agents:write and no **Agent scope**. You don't have permission to create agents in this organization, or you don't work in the workspace metadata.workspace_id names, or no workspace has that ID. Ask an administrator for access, or name a workspace you work in. A custom skill isn't shared with the agent, and the API can't share it for you. Name skills you own, or create the agent in the skill's workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: metadata.workspace_id is a workspace of another organization, or a custom skill you sent doesn't exist or isn't visible to the key's owner. Check the IDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The agent's name. Must be between 1 and 100 characters after leading and trailing spaces are trimmed." }, "model": { "type": "string", "description": "A model ID your deployment runs, or default for your deployment's default model. The object form {id} takes only id." }, "description": { "type": [ "string", "null" ], "description": "The agent's purpose." }, "system": { "type": [ "string", "null" ], "description": "The agent's instructions." }, "tools": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "The agent's built-in tools, as at most one agent_toolset_20260401 entry. Leave it out to get the defaults the app gives a new agent: every tool on with **Allow**, except web_search. Send [] to turn every built-in tool off. tools[].default_config: The setting for each built-in tool that configs doesn't name, as {enabled, permission_policy}. Defaults to {enabled: true, permission_policy: {type: \"always_allow\"}}. web_search stays off whatever this says. tools[].configs: Per-tool settings, each {name, enabled, permission_policy}. name is one of bash, edit, read, write, glob, grep, web_fetch or web_search. permission_policy is {type: \"always_allow\"} or {type: \"always_ask\"}." }, "skills": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "The agent's skills, each {type, skill_id}. Use type anthropic with a built-in skill's slug, such as xlsx, or type custom with a skill ID from [List skills](/build/agent-api/skills/list). version is optional and must be latest." }, "metadata": { "type": "object", "description": "An object whose only key is workspace_id, the ID of a workspace you work in. The API creates the agent in that workspace and does not store metadata." } }, "required": [ "name", "model" ] } } } } } }, "/v1/agents/{agent_id}": { "get": { "operationId": "agents_retrieve", "summary": "Get an agent", "description": "Returns an agent that the calling API key can run. A key can read only the agents in its **Agent scope**, if it has one. An agent ID that does not exist returns 403, not 404: the same response as for an agent outside the key's **Agent scope**.", "tags": [ "Agents" ], "x-capability": "tasks:read", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the agent to return." }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Not supported. Omit it or send 1. Any other value returns 400. Every agent has exactly one version." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" }, "example": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "archived_at": null, "created_at": "2026-10-21T01:35:05.337Z", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "metadata": {}, "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [ { "type": "anthropic", "skill_id": "xlsx", "version": "latest" } ], "system": null, "tools": [ { "type": "agent_toolset_20260401", "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "configs": [ { "type": "bash", "name": "bash", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "edit", "name": "edit", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "read", "name": "read", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "write", "name": "write", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "glob", "name": "glob", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "grep", "name": "grep", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "web_fetch", "name": "web_fetch", "enabled": true, "permission_policy": { "type": "always_ask" }, "url_sources": null }, { "type": "web_search", "name": "web_search", "enabled": false, "permission_policy": { "type": "always_ask" } } ] } ], "type": "agent", "updated_at": "2026-10-21T01:35:05.337Z", "version": 1 } } } }, "400": { "description": "invalid_request_error: version is not 1. Omit version or send 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: The key is not allowed to run this agent, or no agent has this ID. Check the agent ID and the key's **Agent scope**.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "agents_update", "summary": "Update an agent", "description": "Updates an agent. Fields you leave out keep their values. The API applies the same checks as an edit in the Context app. You must be allowed to edit the agent, and the\nkey's **Agent scope**, if it has one, must include the agent. tools and skills replace the whole list when\nyou send them. Every agent has one version, 1: an update changes the agent in place and does not check for\nedits made since you read it, so the last update wins.\n\nIf part of an update is saved and a later part is refused, the error message names the saved fields. Get the\nagent before you retry.", "tags": [ "Agents" ], "x-capability": "agents:write", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the agent to update." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "archived_at": null, "created_at": "2026-10-21T01:35:05.337Z", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "metadata": {}, "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [ { "type": "anthropic", "skill_id": "xlsx", "version": "latest" } ], "system": "Answer in one paragraph.", "tools": [ { "type": "agent_toolset_20260401", "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "configs": [ { "type": "bash", "name": "bash", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "edit", "name": "edit", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "read", "name": "read", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "write", "name": "write", "enabled": true, "permission_policy": { "type": "always_ask" } }, { "type": "glob", "name": "glob", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "grep", "name": "grep", "enabled": true, "permission_policy": { "type": "always_allow" } }, { "type": "web_fetch", "name": "web_fetch", "enabled": true, "permission_policy": { "type": "always_ask" }, "url_sources": null }, { "type": "web_search", "name": "web_search", "enabled": false, "permission_policy": { "type": "always_ask" } } ] } ], "type": "agent", "updated_at": "2026-10-21T02:10:44.918Z", "version": 1 } } } }, "400": { "description": "invalid_request_error: version is not 1. Omit it or send 1. metadata is not empty. Omit it or send {}. To change an agent's workspace, use the Context app. A field breaks a rule of [Create an agent](/build/agent-api/agents/create#errors), such as an unknown model or a custom tool. Fix the field as the matching row there describes. The agent's permission mode is read-only, or its permissions are a hand-written permission block, so its tools can't be changed here. Choose another permission mode for the agent in the app first. The tool settings you sent conflict with the agent's permission mode or with permission rules set in the app. Change those settings in the app, or send tool settings that match them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: This key lacks agents:write, is not a personal key, or its **Agent scope** doesn't include this agent. Use a personal key with agents:write whose **Agent scope**, if any, includes this agent. You are not allowed to edit this agent. Ask its owner for access. A custom skill isn't shared with the agent, and the API can't share it for you. Name skills you own, or move the agent to the skill's workspace in the app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No agent in this key's organization has this ID, or a custom skill you sent doesn't exist or isn't visible to the key's owner. Check the IDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The agent's name. Must be between 1 and 100 characters after leading and trailing spaces are trimmed." }, "description": { "type": [ "string", "null" ], "description": "The agent's purpose. null clears it." }, "system": { "type": [ "string", "null" ], "description": "The agent's instructions. null clears them." }, "model": { "type": "string", "description": "A model ID your deployment runs, or the object form {id}. default removes the agent's own model, so it uses your deployment's default." }, "tools": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "The agent's built-in tool settings, in the same shape as on [Create an agent](/build/agent-api/agents/create). Replaces the whole list. null or [] turns every built-in tool off." }, "skills": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "The agent's skills, in the same shape as on [Create an agent](/build/agent-api/agents/create). Replaces the whole list. null or [] removes them." }, "version": { "type": "integer", "description": "The agent's version. Must be 1. Any other value returns 400." } }, "required": [] } } } } } }, "/v1/environments": { "get": { "operationId": "environments_list", "summary": "List environments", "description": "Lists the environments a session can run in, which is the default cloud environment (env_default). A session can run only in an environment from this list. The API has no call to create environments.", "tags": [ "Environments" ], "x-capability": "tasks:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "The maximum number of environments to return per page. Must be between 1 and 100." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_page value from the previous response. Leave it out to get the first page." }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Has no effect, because environments are never archived." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "env_default", "archived_at": null, "config": { "type": "cloud", "networking": { "type": "unrestricted" }, "packages": { "apt": [], "cargo": [], "gem": [], "go": [], "npm": [], "pip": [] } }, "created_at": "2026-10-14T00:00:00.000Z", "description": "The platform's own runtime. Every session runs here.", "metadata": {}, "name": "default", "type": "environment", "updated_at": "2026-10-14T00:00:00.000Z" } ], "next_page": null } } } }, "400": { "description": "invalid_request_error: limit is outside 1 to 100. Send a value from 1 to 100. page is not a next_page value from this API. Send the next_page value from the previous response, unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/environments/{environment_id}": { "get": { "operationId": "environments_retrieve", "summary": "Get an environment", "description": "Returns one environment, the default cloud environment (env_default). To run a session in this environment, pass its id as environment_id when you create the session.", "tags": [ "Environments" ], "x-capability": "tasks:read", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the environment to retrieve: env_default." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" }, "example": { "id": "env_default", "archived_at": null, "config": { "type": "cloud", "networking": { "type": "unrestricted" }, "packages": { "apt": [], "cargo": [], "gem": [], "go": [], "npm": [], "pip": [] } }, "created_at": "2026-10-14T00:00:00.000Z", "description": "The platform's own runtime. Every session runs here.", "metadata": {}, "name": "default", "type": "environment", "updated_at": "2026-10-14T00:00:00.000Z" } } } }, "404": { "description": "not_found_error: The ID is not env_default. Use env_default.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sessions": { "post": { "operationId": "sessions_create", "summary": "Create a session", "description": "Creates a session for an agent, optionally with files and a first message. Without initial_events the session is idle until you send its first message. With one message it starts at\nonce and is running. If the request fails, it returns an error and no session. If the server already created\nthe session's task in the Context app, it archives it.\n\nFiles sent with a mount_path are copied to the agent's disk, read-only, before the first turn. If a file can't\nbe copied, the session still runs and the file stays in the session's inputs/ folder.", "tags": [ "Sessions" ], "x-capability": "tasks:create", "parameters": [ { "name": "x-context-owner-user-id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The ID of the member who owns the session. A service account key can name any active member of its organization. The member owns the session, sees it in the Context app, and must be able to run the agent. A service account key reads and writes only the sessions it created, including those it created for other members. A personal key can name only its own owner. Send this header or x-context-owner-user-email, not both. Without either, the key's owner owns the session. Only this endpoint takes the owner headers." }, { "name": "x-context-owner-user-email", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The email of the member who owns the session. The same rules apply as for x-context-owner-user-id. Send this header or x-context-owner-user-id, not both." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "dd13d728-93e3-440a-874c-4efeb58c97e0", "agent": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [], "system": null, "tools": [], "type": "agent", "version": 1 }, "archived_at": null, "budget": null, "created_at": "2026-10-21T01:42:16.079Z", "environment_id": "env_default", "metadata": {}, "outcome_evaluations": [], "resources": [ { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "file_id": "329409ba-f288-4b44-9c73-14a18150edee", "mount_path": "inputs/cities.csv", "type": "file", "updated_at": "2026-10-21T01:41:11.028Z" } ], "stats": {}, "status": "running", "title": "Quarterly city report", "type": "session", "updated_at": "2026-10-21T01:42:16.079Z", "usage": { "input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0 }, "active_seconds": 0, "list_cost": null }, "vault_ids": [] } } } }, "400": { "description": "invalid_request_error: A resource isn't a file. Send each resource as {type: \"file\", file_id}, with an optional mount_path. A mount_path is empty, relative, ends in /, holds ., .., a repeated / or a control character, or is too long. Send a normalized absolute path. More than 100 files have a mount_path, two files name the same path, a path sits below another mounted file, or a mounted file is listed twice. Give each mounted file its own path, and list it once. An owner header is empty, or the request sends both x-context-owner-user-id and x-context-owner-user-email. Send one header with a member's ID or email, or omit both so the key's owner owns the session. The named owner isn't an active member of this key's organization. Check the ID or email. initial_events holds more than one event, or one that isn't a user.message. Send at most one user.message, then send the rest with [Send events](/build/agent-api/events/send). The title is over 280 characters. Shorten it. The body sends non-empty metadata or vault_ids, a non-null budget, or agent overrides (any field in the agent object besides type, id and version). Remove them. A file_id names a file a session produced, which can't be attached. Download it and upload it, then attach the upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: The key lacks tasks:create, or isn't allowed to run this agent. An unknown agent ID returns the same 403. Check the agent ID and the key's capabilities. A personal key names a member other than its owner. Use a service account key to create sessions for other members, or omit the header. The named owner can't run this agent. Pick an agent the member can run, or name another member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: environment_id isn't env_default. Check the ID with [List environments](/build/agent-api/environments/list). A file_id isn't a file this key can read. Check the ID with [List files](/build/agent-api/files/list).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "const": "agent" }, "id": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "type", "id" ], "additionalProperties": false } ], "description": "An agent ID from [List agents](/build/agent-api/agents/list). The object form is also accepted. Each agent has one version, so version must be 1 or left out. Any other field in the object returns 400. An unknown agent ID returns 403, not 404." }, "environment_id": { "type": "string", "description": "The environment to run the session in: env_default. Any other ID returns 404. See [Environments](/build/agent-api/environments/overview)." }, "title": { "type": "string", "description": "The session's title. The maximum length is 280 characters. Default: The first 80 characters of the first message, or API session." }, "initial_events": { "type": "array", "items": { "type": "object" }, "description": "The events to start the session with. The array can hold at most one event, and it must be a user.message. See [Send events](/build/agent-api/events/send). The response can return before the first turn starts. Before you send another message, wait for session.status_running on the [event stream](/build/agent-api/events/stream)." }, "resources": { "type": "array", "items": { "type": "object" }, "description": "The files to give the agent. Each is a {type: \"file\", file_id, mount_path} object, with a file_id from [Upload a file](/build/agent-api/files/upload). Up to 50 files. A request with more than 50 files returns 500 instead of a named 400, which is a known defect. resources[].mount_path: Where to put the file on the agent's disk, read-only. A path under /workspace/ or /mnt/session/uploads/ is used as given. Any other absolute path is placed under /mnt/session/uploads, so /data/a.csv becomes /mnt/session/uploads/data/a.csv. The maximum length is 4096 characters, and 255 bytes per path segment. Without it, the file is only in the session's inputs/ folder." }, "metadata": { "type": "object", "description": "Not supported. Omit it or send {}. Any other value returns 400." }, "vault_ids": { "type": "array", "items": { "type": "string" }, "description": "Not supported. Omit it or send []. Any other value returns 400." }, "budget": { "type": [ "object", "null" ], "description": "Not supported. Omit it or send null. Any other value returns 400." } }, "required": [ "agent", "environment_id" ] }, "example": { "agent": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "environment_id": "env_default", "title": "Quarterly city report", "resources": [ { "type": "file", "file_id": "329409ba-f288-4b44-9c73-14a18150edee" } ], "initial_events": [ { "type": "user.message", "content": [ { "type": "text", "text": "Read the attached cities.csv and name the largest city." } ] } ] } } } } }, "get": { "operationId": "sessions_list", "summary": "List sessions", "description": "Lists the sessions this key can see, newest first. A personal key reads its owner's sessions, including sessions a service account key created for its owner. A\nservice account key reads only the sessions it created, whoever owns them. If the key is limited to specific agents (its **Agent scope**), it reads only those\nagents' sessions.\n\nThe statuses filter applies after the server reads each page.", "tags": [ "Sessions" ], "x-capability": "tasks:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "The maximum number of sessions to return. Must be between 1 and 100." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_page value from the previous response. Leave it out to get the first page." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The ID of the agent whose sessions to return." }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to include archived sessions." }, { "name": "statuses", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "The statuses to return: idle, running or terminated. rescheduling is accepted for compatibility but never matches a session. To pass more than one, repeat the parameter: statuses[]=idle&statuses[]=running." }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The earliest creation time to include, as an RFC 3339 timestamp. created_at[gt] (after), created_at[lt] (before) and created_at[lte] (at or before) filter the same field." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc" }, "description": "Not supported. Omit it or send desc. Any other value returns 400." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "dd13d728-93e3-440a-874c-4efeb58c97e0", "agent": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [], "system": null, "tools": [], "type": "agent", "version": 1 }, "archived_at": null, "budget": null, "created_at": "2026-10-21T01:42:16.079Z", "environment_id": "env_default", "metadata": {}, "outcome_evaluations": [], "resources": [ { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "file_id": "329409ba-f288-4b44-9c73-14a18150edee", "mount_path": "inputs/cities.csv", "type": "file", "updated_at": "2026-10-21T01:41:11.028Z" } ], "stats": {}, "status": "idle", "title": "Quarterly city report", "type": "session", "updated_at": "2026-10-21T01:42:29.719Z", "usage": { "input_tokens": 12, "output_tokens": 318, "cache_read_input_tokens": 133496, "cache_creation": { "ephemeral_5m_input_tokens": 2210, "ephemeral_1h_input_tokens": 0 }, "active_seconds": 7.331, "list_cost": { "amount": "6", "currency": "USD" } }, "vault_ids": [] } ], "next_page": null, "prev_page": null } } } }, "400": { "description": "invalid_request_error: order is any value other than desc. Omit order. statuses contains an unknown value. Send only idle, running, terminated or rescheduling. The request includes agent_version, deployment_id or memory_store_id, which this API does not take. Remove them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sessions/{session_id}": { "get": { "operationId": "sessions_retrieve", "summary": "Get a session", "description": "Returns a session with its status and token totals.", "tags": [ "Sessions" ], "x-capability": "tasks:read", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the session to retrieve." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" }, "example": { "id": "dd13d728-93e3-440a-874c-4efeb58c97e0", "agent": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [], "system": null, "tools": [], "type": "agent", "version": 1 }, "archived_at": null, "budget": null, "created_at": "2026-10-21T01:42:16.079Z", "environment_id": "env_default", "metadata": {}, "outcome_evaluations": [], "resources": [ { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "file_id": "329409ba-f288-4b44-9c73-14a18150edee", "mount_path": "inputs/cities.csv", "type": "file", "updated_at": "2026-10-21T01:41:11.028Z" } ], "stats": {}, "status": "idle", "title": "Quarterly city report", "type": "session", "updated_at": "2026-10-21T01:42:29.719Z", "usage": { "input_tokens": 12, "output_tokens": 318, "cache_read_input_tokens": 133496, "cache_creation": { "ephemeral_5m_input_tokens": 2210, "ephemeral_1h_input_tokens": 0 }, "active_seconds": 7.331, "list_cost": { "amount": "6", "currency": "USD" } }, "vault_ids": [] } } } }, "404": { "description": "not_found_error: No session with this ID exists, or this key can't read it. Check the session ID and the key you are using.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "sessions_update", "summary": "Rename a session", "description": "Changes a session's title and returns the updated session. Only the title can change. Sending agent, vault_ids, budget or a non-empty metadata returns 400. An empty body, or metadata: {}, returns 200 and changes nothing.", "tags": [ "Sessions" ], "x-capability": "tasks:create", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the session to rename." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "dd13d728-93e3-440a-874c-4efeb58c97e0", "agent": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [], "system": null, "tools": [], "type": "agent", "version": 1 }, "archived_at": null, "budget": null, "created_at": "2026-10-21T01:42:16.079Z", "environment_id": "env_default", "metadata": {}, "outcome_evaluations": [], "resources": [ { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "file_id": "329409ba-f288-4b44-9c73-14a18150edee", "mount_path": "inputs/cities.csv", "type": "file", "updated_at": "2026-10-21T01:41:11.028Z" } ], "stats": {}, "status": "idle", "title": "Q3 city report", "type": "session", "updated_at": "2026-10-21T01:42:29.719Z", "usage": { "input_tokens": 12, "output_tokens": 318, "cache_read_input_tokens": 133496, "cache_creation": { "ephemeral_5m_input_tokens": 2210, "ephemeral_1h_input_tokens": 0 }, "active_seconds": 7.331, "list_cost": { "amount": "6", "currency": "USD" } }, "vault_ids": [] } } } }, "400": { "description": "invalid_request_error: The title is empty, contains only whitespace or is longer than 280 characters. Send a title of 1 to 280 characters, or null to clear it. The body includes agent, vault_ids, budget or a non-empty metadata. Send only title.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: The key does not act for the session's owner, or the owner is no longer an active member. Use the owner's personal key or the service account key that created the session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No session with this ID exists, or this key can't read it. Check the session ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "description": "The new title. Must be between 1 and 280 characters after trimming (Anthropic: 500). Send null to clear the title." } }, "required": [] }, "example": { "title": "Q3 city report" } } } } }, "delete": { "operationId": "sessions_delete", "summary": "Delete a session", "description": "Permanently deletes a session and its data. Deleting removes the session's task in the Context app and the tasks of its subagents, with their events and\ntranscripts. It also removes the session's inputs/ copies and outputs, its sandbox and saved workspace, its\nLLM traces, and the memories its runs saved. The session no longer appears in the task history in the Context\napp, and any open stream on the session ends. [Response](#response) lists what stays.\n\nDelete a session with the owner's personal key or with the service account key that created it. Keys don't have\nsessions:delete by default. The key's owner must grant it when creating the key, and an existing key can't gain\nit.\n\nNothing deletes a session for you. Your deployment keeps a session and its history until you delete it with\nthis request, and archiving a session keeps its history too.\n\nIf a turn is running, the request returns 409 and the turn keeps running. Send a user.interrupt, wait for\nthe session to go idle, then delete it. A session waiting for a tool approval counts as idle. If another change\nto the session is in progress, for example an event you sent, the delete can return 409. The session still\nexists, but its traces, saved workspace and recordings may already be deleted. Retry the delete.\nFiles you uploaded with [Upload a file](/build/agent-api/files/upload) are kept. Delete them with\n[Delete a file](/build/agent-api/files/delete).", "tags": [ "Sessions" ], "x-capability": "sessions:delete", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the session to delete." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "dd13d728-93e3-440a-874c-4efeb58c97e0", "type": "session_deleted", "removed": { "tasks": 1, "runs": 1, "sandboxes": 1, "dispatch_rows_scrubbed": 1, "approval_previews_purged": 0, "billing_events_unlinked": 2, "agent_memories_deleted": 3, "traces": "deleted" }, "kept": [ { "store": "billing_meter_events", "reason": "..." }, { "store": "audit_log", "reason": "..." }, { "store": "dispatch_ledger_rows", "reason": "..." }, { "store": "uploaded_files", "reason": "..." }, { "store": "agent_memory_notes", "reason": "..." }, { "store": "storage_residue", "reason": "..." } ] } } } }, "400": { "description": "invalid_request_error: The request sends a query parameter. Remove it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: The key lacks sessions:delete. Create a key that has sessions:delete. Only the key's owner can grant it. The key doesn't act for the session's owner. Use the owner's personal key or the service account key that created the session. The session's owner doesn't have permission to delete it in the Context app, or is no longer an active member. No key can delete the session in that case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No session with this ID exists, it is already deleted, or this key can't read it. Check the session ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "invalid_request_error: A turn is running. Send a user.interrupt, wait until the session is idle, then delete it. Another change to the session was in progress. The session still exists, but its traces, saved workspace and recordings may already be deleted. Retry the delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: The session's traces couldn't be removed, so the session wasn't deleted. Retry the delete. An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sessions/{session_id}/archive": { "post": { "operationId": "sessions_archive", "summary": "Archive a session", "description": "Ends a session permanently. Its history stays readable. The status becomes terminated. After that, sending an event to the session returns 400, and an open stream\nends with an invalid_request_error frame. Archiving an archived session returns it unchanged. To remove a\nsession's data permanently, [delete it](/build/agent-api/sessions/delete) instead. To list archived sessions, call\n[List sessions](/build/agent-api/sessions/list) with include_archived=true.\n\nYou can archive a running session. Its current turn is not cut short, and the run stops once the turn is over.\nTo stop the turn at once, send a user.interrupt before you archive.", "tags": [ "Sessions" ], "x-capability": "tasks:create", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the session to archive." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "dd13d728-93e3-440a-874c-4efeb58c97e0", "agent": { "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60", "description": "Answers questions about the sales pipeline", "execution_identity": { "type": "service_account" }, "mcp_servers": [], "model": { "id": "default" }, "multiagent": null, "name": "Research Assistant", "skills": [], "system": null, "tools": [], "type": "agent", "version": 1 }, "archived_at": "2026-10-21T01:47:50.964Z", "budget": null, "created_at": "2026-10-21T01:42:16.079Z", "environment_id": "env_default", "metadata": {}, "outcome_evaluations": [], "resources": [ { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "file_id": "329409ba-f288-4b44-9c73-14a18150edee", "mount_path": "inputs/cities.csv", "type": "file", "updated_at": "2026-10-21T01:41:11.028Z" } ], "stats": {}, "status": "terminated", "title": "Quarterly city report", "type": "session", "updated_at": "2026-10-21T01:47:50.964Z", "usage": { "input_tokens": 12, "output_tokens": 318, "cache_read_input_tokens": 133496, "cache_creation": { "ephemeral_5m_input_tokens": 2210, "ephemeral_1h_input_tokens": 0 }, "active_seconds": 7.331, "list_cost": { "amount": "6", "currency": "USD" } }, "vault_ids": [] } } } }, "403": { "description": "permission_error: The key does not act for the session's owner, or the owner is no longer an active member. Use the owner's personal key or the service account key that created the session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No session with this ID exists, or this key can't read it. Check the session ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sessions/{session_id}/events": { "get": { "operationId": "events_list", "summary": "List events", "description": "Returns a session's event history, oldest first by default.", "tags": [ "Events" ], "x-capability": "tasks:read", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the session whose events to return." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100 }, "description": "The maximum number of events to return on one page. Must be between 1 and 1000." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "default": "asc" }, "description": "The sort order. One of asc (oldest first) or desc (newest first)." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The ID of the event to start from. To fetch the next page, pass the next_page value from the previous response. With asc, the page starts with the first event after this one. With desc, it starts with the first event before it. The event itself is not included." }, { "name": "types", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "The event types to return. To pass more than one, repeat the parameter: types[]=agent.message&types[]=session.status_idle." }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The earliest processed_at time to include, as an RFC 3339 timestamp. created_at[gt] (after), created_at[lt] (before) and created_at[lte] (at or before) filter the same field." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "type": "user.message", "id": "sevt_1_0", "processed_at": "2026-10-21T01:42:16.357Z", "content": [ { "type": "text", "text": "Run this bash command and tell me the output: echo first" } ] }, { "type": "session.status_running", "id": "sevt_1_1", "processed_at": "2026-10-21T01:42:16.357Z" }, { "type": "agent.tool_use", "id": "sevt_29_0", "processed_at": "2026-10-21T01:42:21.908Z", "name": "bash", "input": { "command": "echo first" } } ], "next_page": null } } } }, "400": { "description": "invalid_request_error: limit is outside 1 to 1000. Send a value from 1 to 1000. order is not asc or desc. Send one of them, or omit it. page is not an event ID this API issued. Send the next_page value from the previous response, unchanged. A created_at bound is not an RFC 3339 timestamp. Send a timestamp such as 2026-10-21T01:42:16Z.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No session with this ID exists, or this key can't read it. Check the session ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "events_send", "summary": "Send events", "description": "Sends a message, a tool approval or an interrupt to a session. Sends are not idempotent. If a send times out or its result is unknown, read the session's events before you\nsend it again.\n\nThe server checks every event against the session before any of them acts, then applies them in order. If an\nevent is refused while they are applied, because the session changed in the meantime, the earlier events stay\naccepted and the error message says how many were. Don't resend those.\n\nEach event gets a receipt with a sevt_receipt_ ID and processed_at: null. The stored event, with its real\nID, then appears on the stream and in the history. The receipt ID is not the stored event's ID, so match the\nstored event on the stream rather than by ID.\n\nBefore a session starts, it accepts exactly one user.message per request. Send more only after the stream\nshows session.status_running. A user.message sent while a turn runs is added to that turn instead of\nstarting a new one.\n\nA user.tool_confirmation also needs the tasks:approve capability and a\n[personal key](/build/agent-api/choosing-a-key).", "tags": [ "Events" ], "x-capability": "tasks:create", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the session to send events to." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "type": "user.message", "content": [ { "type": "text", "text": "Now chart the top three." } ], "id": "sevt_receipt_219b3afe-157c-452d-981b-c71353fb80bc", "processed_at": null } ] } } } }, "400": { "description": "invalid_request_error: An event is malformed, or its text is empty or over 100,000 characters in all. Fix the event the message names. The session is archived. Archived sessions take no events. Create a new session. The session has not started and the request holds more than one user.message, or the first turn is still starting. Send one message, then wait for session.status_running before you send the next. A tool_use_id is unknown, repeated or already answered. Send only IDs from the latest stop_reason.event_ids that you have not answered. An event has a type this endpoint does not accept: user.tool_result, user.custom_tool_result, user.define_outcome or system.message. Send only user.message, user.tool_confirmation or user.interrupt. An event carries session_thread_id. Sessions have one thread. Remove session_thread_id and retry. A user.tool_confirmation follows a user.interrupt in the same request. Send the confirmation before the interrupt, or in a separate request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: The key does not act for the session's owner, or the owner is no longer an active member. Use the owner's personal key or the service account key that created the session. A user.tool_confirmation was sent with a key that is not personal, or that lacks tasks:approve. Use a personal key with tasks:approve.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No session with this ID exists, or this key can't read it. Check the session ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "invalid_request_error: The session's state changed while the request was processed. The tool call was already answered, or the session is stopping or moving. Read the events, then decide whether to send again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object" }, "description": "The events to send, applied in order. events[].type: The event type. One of user.message, user.tool_confirmation or user.interrupt. events[].content: One or more {type: \"text\", text} blocks, up to 100,000 characters in all. Required for user.message. events[].tool_use_id: The ID of the agent.tool_use event to answer, from stop_reason.event_ids on the session.status_idle event. Required for user.tool_confirmation. events[].result: One of allow (approves this one call) or deny. Required for user.tool_confirmation. events[].deny_message: Text stored with your answer. The receipt echoes it whenever you send it. The stored user.tool_confirmation event carries it only for a deny. Its length is limited only by the 10 MiB request body limit." } }, "required": [ "events" ] }, "example": { "events": [ { "type": "user.message", "content": [ { "type": "text", "text": "Now chart the top three." } ] } ] } } } } } }, "/v1/sessions/{session_id}/events/stream": { "get": { "operationId": "events_stream", "summary": "Stream events", "description": "Streams a session's events as server-sent events while they happen. Without Last-Event-ID, the stream sends only events that happen after it opens, so open it before you send a\nmessage.\n\nEach key can hold up to 24 open streams across all its sessions, unless your deployment sets a different limit.\nThe limit applies on each server instance, so a key whose streams land on more than one instance can hold more\nin total. A stream counts until your client disconnects.", "tags": [ "Events" ], "x-capability": "tasks:read", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the session to stream." }, { "name": "event_deltas", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Not supported. Omit it. Any value returns 400." }, { "name": "Last-Event-ID", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The ID of the last event you received from this session. The stream replays every event after it, then continues live. sevt_0_0 replays from the start. A send receipt's ID (sevt_receipt_, returned when you [send an event](/build/agent-api/events/send)) returns 400." } ], "responses": { "200": { "description": "Server-Sent Events", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": ": open\n\nid: sevt_40_0\nevent: agent.message\ndata: {\"type\":\"agent.message\",\"id\":\"sevt_40_0\",\"processed_at\":\"2026-10-21T01:42:24.003Z\",\"content\":[{\"type\":\"text\",\"text\":\"The output is `first`.\"}]}\n\nid: sevt_40_1\nevent: session.usage\ndata: {\"type\":\"session.usage\",\"id\":\"sevt_40_1\",\"processed_at\":\"2026-10-21T01:42:24.003Z\",\"usage\":{\"input_tokens\":6,\"output_tokens\":82,\"cache_read_input_tokens\":44428,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"active_seconds\":7.288}}\n\nid: sevt_41_0\nevent: session.usage\ndata: {\"type\":\"session.usage\",\"id\":\"sevt_41_0\",\"processed_at\":\"2026-10-21T01:42:24.043Z\",\"usage\":{\"input_tokens\":6,\"output_tokens\":82,\"cache_read_input_tokens\":44428,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"active_seconds\":7.331}}\n\nid: sevt_41_1\nevent: session.status_idle\ndata: {\"type\":\"session.status_idle\",\"id\":\"sevt_41_1\",\"processed_at\":\"2026-10-21T01:42:24.043Z\",\"stop_reason\":{\"type\":\"end_turn\"},\"stop_details\":null}\n\nevent: ping\ndata: {\"type\":\"ping\"}\n" } } }, "400": { "description": "invalid_request_error: Last-Event-ID is not an event ID of this session. Send an ID from this session's events, or omit the header. The request includes the event_deltas query parameter. Remove it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No session with this ID exists, or this key can't read it. Check the session ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: This key already holds the most open streams allowed on the server instance that answered, 24 by default. Close a stream you no longer read, then retry. The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files": { "post": { "operationId": "files_upload", "summary": "Upload a file", "description": "Uploads one file to the Drive of the user who owns the key. Send multipart/form-data with one file field, whose part includes a filename, and optionally an\nexpires_in_seconds field. The server accepts any file type. In a body over 10 MiB, expires_in_seconds must\ncome before file. The Python and .NET SDKs send it first. With the TypeScript SDK, write expires_in_seconds\nbefore file in the object you pass to files.upload.\n\nThese limits apply:\n\n- A file can be up to your deployment's upload limit, which is 5 GiB unless your administrator set it lower.\n- Send a Content-Length header. cURL and the SDKs send one for you. A request without one must use chunked\n encoding and be 10 MiB or smaller.\n- Each key can have up to 4 uploads in progress on one server instance, and each instance takes up to 8 in\n total across all keys. Keep 4 or fewer uploads in progress, and retry on 429.\n\nIf the request fails partway, the server keeps nothing.", "tags": [ "Files" ], "x-capability": "files:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" }, "example": { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "filename": "cities.csv", "mime_type": "text/csv", "size_bytes": 46, "type": "file", "downloadable": true } } } }, "400": { "description": "invalid_request_error: The form has a field other than file and expires_in_seconds. Remove the other fields. expires_in_seconds isn't a whole number between 3600 and 7776000. Send a value in that range, or omit it. expires_in_seconds comes after file in a body over 10 MiB. Send expires_in_seconds before file, or omit it. The form has no file field, or more than one, or the filename is empty. Send exactly one file field with a non-empty filename. The body doesn't match its Content-Length: bytes follow the closing boundary, or the body ends early. The server keeps nothing. Send an exact Content-Length.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large: The file is over your deployment's upload limit (5 GiB unless your administrator set it lower), or a chunked request is over 10 MiB. The message gives the limit. If the file is over the upload limit, send a smaller file. If the request is chunked and over 10 MiB, send it again with a Content-Length header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: This key already has 4 uploads in progress on the server instance that answered, or 8 are in progress there for all keys. Wait for the time in Retry-After, then retry. The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file, with a filename. If the part has no media type, the server stores the file as application/octet-stream." }, "expires_in_seconds": { "type": "integer", "description": "The number of seconds until the file expires on Anthropic's API. Must be a whole number between 3600 and 7776000. It isn't applied: the file is kept until you delete it, and the file object has no expires_at." } }, "required": [ "file" ] } } } } }, "get": { "operationId": "files_list", "summary": "List files", "description": "Lists the files this key or its owner uploaded, or the files a session produced, newest first. Without scope_id, the list holds files uploaded with a Task API key: the files this key uploaded, and the\nfiles that this key's owner owns. With scope_id set to a session ID, the list holds the files that session's\nagent produced, each with a scope field that names the session. That list leaves out the session's attached\nfiles, the files the platform stores for the session (such as its transcript), and large tool results saved\nduring the session. The list stays the same after the session is archived.\n\nSend at most one of page, after_id and before_id. Both SDKs paginate with page.", "tags": [ "Files" ], "x-capability": "files:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "The maximum number of files to return. Must be between 1 and 100." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_page value from the previous response. Leave it out to get the first page." }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The ID of a file. Returns files older than that file. Pass last_id from the previous page." }, { "name": "before_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The ID of a file. Returns files newer than that file. Pass first_id from the previous page." }, { "name": "scope_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A session ID. Returns the files that session's agent produced instead of the default list." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "filename": "cities.csv", "mime_type": "text/csv", "size_bytes": 46, "type": "file", "downloadable": true } ], "next_page": null, "has_more": false, "first_id": "329409ba-f288-4b44-9c73-14a18150edee", "last_id": "329409ba-f288-4b44-9c73-14a18150edee" } } } }, "400": { "description": "invalid_request_error: limit is outside 1 to 100. Send a value from 1 to 100. The request sends more than one of page, after_id and before_id. Send only one of them. The request sends ids, which this API doesn't take. Remove it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: after_id or before_id names a file that isn't on this list. Pass first_id or last_id from a previous page of this list. scope_id names a session this key can't read. Pass the ID of a session this key can read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{file_id}": { "get": { "operationId": "files_retrieve", "summary": "Get a file", "description": "Returns a file's metadata. To get the file's content, see [Download a file](/build/agent-api/files/download).", "tags": [ "Files" ], "x-capability": "files:read", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the file to retrieve." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" }, "example": { "id": "329409ba-f288-4b44-9c73-14a18150edee", "created_at": "2026-10-21T01:41:11.028Z", "filename": "cities.csv", "mime_type": "text/csv", "size_bytes": 46, "type": "file", "downloadable": true } } } }, "404": { "description": "not_found_error: No file with this ID exists, or this key can't read it or the session that produced it. Check the ID from the upload or from the list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "files_delete", "summary": "Delete a file", "description": "Permanently deletes an uploaded file. The file doesn't go to the Drive trash, and it can't be restored through this API or the app. A later request\nfor it returns 404. If the server can't delete the stored copy, the request returns 500 and the copy stays in\nthe owner's Drive. See the errors below.\n\nA service account key can delete only the files it uploaded. This endpoint can't delete files that a session\nproduced, or a file that a session or run still uses. See the errors below.", "tags": [ "Files" ], "x-capability": "files:write", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the file to delete." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "329409ba-f288-4b44-9c73-14a18150edee", "type": "file_deleted" } } } }, "400": { "description": "invalid_request_error: The file is attached to a session that isn't archived, or is used by a run that hasn't finished. Archive the session, or wait for the run to finish, then retry. The file was produced by a session. Download it with [Download a file](/build/agent-api/files/download), or remove it from the session's folder in Drive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: The key lacks files:write. Use a key that has files:write. The key's owner can't edit the Drive folder that holds the file. Use a key whose owner can edit that folder. A service account key tried to delete a file it didn't upload. Use the personal key of the user who owns the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No file with this ID exists, or this key can't read it. Check the ID against [List files](/build/agent-api/files/list). If the ID is correct, check that the key can read the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: The API no longer returns the file, but its stored copy couldn't be deleted. The message says where the copy remains in the owner's Drive. Delete it there, or quote request_id when you contact support. An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{file_id}/content": { "get": { "operationId": "files_download", "summary": "Download a file", "description": "Returns a file's content exactly as it was uploaded or as a session wrote it. For an uploaded file, the file's owner must be able to read it in Drive. For a file a session produced, the key\nmust be able to read that session and the file in Drive. If a check fails, the request returns 404.\n\nThe server streams the content, so the response has no content-length header. To read the file's name, size\nand media type without downloading it, see [Get a file](/build/agent-api/files/retrieve).", "tags": [ "Files" ], "x-capability": "files:read", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the file to download." } ], "responses": { "200": { "description": "The file's bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "description": "billing_error: The file is a session's output, and your deployment requires a paid plan or credits before you can download session output. Add a plan or credits in the app, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No file with this ID exists, or this key can't read the file or the session that produced it. Check the ID against the upload response or [List files](/build/agent-api/files/list). If the ID is correct, check the access rules on this page. The file's content is no longer stored. If you uploaded the file, upload it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/skills": { "post": { "operationId": "skills_create", "summary": "Create a skill", "description": "Creates a skill from uploaded files. The skill belongs to the owner of the API key. Send multipart/form-data with the skill's files in files[]. To upload a zip archive instead, send it as the\nonly files[] part. For the rules an upload must follow, see\n[Skills](/build/agent-api/skills/overview#what-an-upload-contains). Only the key's owner can see\nthe skill until they share it in the Context app.\n\nIf the request fails partway, the server deletes the skill, so no partial skill is left. If your organization\nuses the newer permissions model, a skill uploaded with files besides SKILL.md is saved as two versions:\nSKILL.md alone, then the whole upload. latest_version_id always points to the version that holds the whole\nupload.", "tags": [ "Skills" ], "x-capability": "skills:write", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" }, "example": { "id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e", "type": "skill", "created_at": "2026-10-27T15:02:11.204Z", "display_name": "pr-summary", "latest_version_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "source": { "type": "custom" }, "updated_at": "2026-10-27T15:02:11.204Z" } } } }, "400": { "description": "invalid_request_error: The upload breaks a rule: SKILL.md is missing or not at the root, name or description is missing or invalid, a path is unsafe, or the files total over 30 MiB (31,457,280 bytes) uncompressed. The message names the rule. Fix the files and upload again. display_name is not the name in SKILL.md. Leave it out, or send that name. The form has a field other than files[] and display_name, or the request has a query parameter. Remove it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: The key lacks skills:write, is not a personal key, or its owner doesn't have permission to create skills in this organization. Use a personal key with skills:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "invalid_request_error: The key's owner already has a skill with this name. The message gives its ID. Upload a new version of that skill, or change name in SKILL.md.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large: The request is over 32 MiB (33,554,432 bytes). Remove files until the request is under 32 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: This key already has 2 skill uploads in progress, or the server is processing too many uploads. Wait for the time in Retry-After, then retry. The SDKs retry it for you. The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "The skill's files. On the wire each file is one files[] part, with the file's path in the skill as the filename. The SDKs send the files parameter this way. You can instead send one zip archive that contains all the files." }, "display_name": { "type": "string", "description": "The skill's display name. Must equal the name in SKILL.md." } }, "required": [ "files" ] } } } } }, "get": { "operationId": "skills_list", "summary": "List skills", "description": "Lists the skills the key's owner can read. The list holds your organization's skills that the key's owner can read, and the built-in skills. Skills an\nadministrator has marked as verified come first, then the rest by updated_at, newest first. The list leaves\nout skills shared from another organization, archived skills and skills with no version yet.", "tags": [ "Skills" ], "x-capability": "skills:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "The maximum number of skills to return. Must be between 1 and 200." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_page value from the previous response. Leave it out to get the first page." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The set of skills to return. One of custom (your organization's skills) or anthropic (built-in skills). Leave it out to return both." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e", "type": "skill", "created_at": "2026-10-27T15:02:11.204Z", "display_name": "pr-summary", "latest_version_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "source": { "type": "custom" }, "updated_at": "2026-10-27T15:02:11.204Z" }, { "id": "pptx", "type": "skill", "created_at": "2026-10-14T00:00:00.000Z", "display_name": "pptx", "latest_version_id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "source": { "type": "anthropic" }, "updated_at": "2026-10-20T00:00:00.000Z" } ], "next_page": null } } } }, "400": { "description": "invalid_request_error: limit is outside 1 to 200. Send a value from 1 to 200. source is not custom or anthropic. Send one of them, or leave it out. The request has a query parameter other than limit, page and source. Remove it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/skills/{skill_id}": { "get": { "operationId": "skills_retrieve", "summary": "Get a skill", "description": "Returns a skill by its ID. To get a built-in skill, pass its slug, such as pptx, as skill_id. Archived skills and skills with no version return 404.", "tags": [ "Skills" ], "x-capability": "skills:read", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the skill, or a built-in skill's slug." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Skill" }, "example": { "id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e", "type": "skill", "created_at": "2026-10-27T15:02:11.204Z", "display_name": "pr-summary", "latest_version_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "source": { "type": "custom" }, "updated_at": "2026-10-27T15:02:11.204Z" } } } }, "404": { "description": "not_found_error: No skill with this ID exists, the key's owner can't read it, the skill is archived, or it has no version yet. Check the ID and the key. To get an archived skill, unarchive it in the Context app. To get a skill with no version, [create a version](/build/agent-api/skills/versions-create) first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "skills_delete", "summary": "Delete a skill", "description": "Deletes a skill, its versions and their files. The skill is also removed from every agent it is assigned to. A built-in skill can't be deleted. The key's owner must be able to edit the skill. The delete can't be undone. In some organizations the skill's files are kept in Drive trash until the trash is emptied.", "tags": [ "Skills" ], "x-capability": "skills:write", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the skill to delete." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e", "type": "skill_deleted" } } } }, "400": { "description": "invalid_request_error: The skill is a built-in skill, which is read-only. Check that the ID is a custom skill's.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: The key lacks skills:write, is not a personal key, or its owner can't edit this skill. Use a personal key with skills:write whose owner can edit the skill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No skill with this ID exists, or the key's owner can't read it. Check the ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/skills/{skill_id}/versions": { "post": { "operationId": "skills_versions-create", "summary": "Create a skill version", "description": "Saves a new version of a skill from its complete set of files. Send every file of the skill, the same way as for\n[Create a skill](/build/agent-api/skills/create). A version is a whole snapshot: any file you\nleave out is not in the new version. The name in SKILL.md must be the skill's name. The key's owner must be\nable to edit the skill.\n\nThe upload becomes the skill's newest version at once, so agents that have the skill use this version from\ntheir next session. An upload identical to the newest version saves nothing and returns that version.", "tags": [ "Skills" ], "x-capability": "skills:write", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the skill." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "type": "skill_version", "created_at": "2026-10-27T15:02:11.388Z", "description": "Summarize a pull request for reviewers.", "name": "pr-summary", "skill_id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e" } } } }, "400": { "description": "invalid_request_error: The upload breaks a rule, such as SKILL.md missing or the files totaling over 30 MiB (31,457,280 bytes) uncompressed. The message names the rule. Fix the files and upload again. The name in SKILL.md is not the skill's name. Keep the skill's name, or create a separate skill. The skill is a built-in skill, which is read-only. Create your own skill instead. The form has a field other than files[]. Remove it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "permission_error: The key lacks skills:write, is not a personal key, or its owner can't edit this skill. Use a personal key with skills:write whose owner can edit the skill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No skill with this ID exists, or the key's owner can't read it. Check the ID, and check that the key's owner can read the skill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "request_too_large: The request is over 32 MiB (33,554,432 bytes). Remove files until the request is under 32 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: This key already has 2 skill uploads in progress, or the server is processing too many uploads. Wait for the time in Retry-After, then retry. The SDKs retry it for you. The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "The skill's files. On the wire each file is one files[] part, with the file's path in the skill as the filename. The SDKs send the files parameter this way. You can instead send one zip archive that contains all the files." } }, "required": [ "files" ] } } } } }, "get": { "operationId": "skills_versions-list", "summary": "List skill versions", "description": "Lists a skill's versions, newest first. You can't delete a single version: DELETE /v1/skills/{skill_id}/versions/{version} returns 400. To replace a version, [upload a new one](/build/agent-api/skills/versions-create). To remove every version, [delete the skill](/build/agent-api/skills/delete).", "tags": [ "Skills" ], "x-capability": "skills:read", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the skill, or a built-in skill's slug." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "The maximum number of versions to return. Must be between 1 and 100." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_page value from the previous response. Leave it out to get the first page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "type": "skill_version", "created_at": "2026-10-27T15:02:11.388Z", "description": "Summarize a pull request for reviewers.", "name": "pr-summary", "skill_id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e" } ], "next_page": null } } } }, "400": { "description": "invalid_request_error: limit is outside 1 to 100. Send a value from 1 to 100.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No skill with this ID or slug exists, or the key's owner can't read it. Check the ID or slug, and that the key's owner can read the skill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/skills/{skill_id}/versions/{version}": { "get": { "operationId": "skills_versions-retrieve", "summary": "Get a skill version", "description": "Returns one version of a skill, or its newest version if you pass latest as version.", "tags": [ "Skills" ], "x-capability": "skills:read", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the skill, or a built-in skill's slug." }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The version's ID, or latest." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "type": "skill_version", "created_at": "2026-10-27T15:02:11.388Z", "description": "Summarize a pull request for reviewers.", "name": "pr-summary", "skill_id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e" } } } }, "404": { "description": "not_found_error: No skill with this ID or slug exists, the key's owner can't read it, or the version is not one of this skill's. Check skill_id and version, and that the key's owner can read the skill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/skills/{skill_id}/versions/{version}/content": { "get": { "operationId": "skills_versions-content", "summary": "Download a skill version", "description": "Returns a version's files as one zip archive. The archive holds SKILL.md and the supporting files under one folder named after the skill's name, the same layout that [Create a skill version](/build/agent-api/skills/versions-create) accepts. The zip file has the same name. If a skill made in the Context app has a name with other characters than lowercase letters, digits and hyphens, the folder name is rewritten in those characters, so Q3 / Q4 report becomes q3-q4-report. If no letters or digits are left, the folder is named after the skill's ID. Pass latest as version for the newest version.", "tags": [ "Skills" ], "x-capability": "skills:read", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the skill, or a built-in skill's slug." }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The version's ID, or latest." } ], "responses": { "200": { "description": "A zip archive of the version's files", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "invalid_request_error: The version was saved before your deployment stored skill file contents, so the server has no files to return. Download a later version. If none exists, upload the skill's files again as a new version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found_error: No skill with this ID or slug exists, the key's owner can't read it, or the version is not one of this skill's. Check skill_id and version, and that the key's owner can read the skill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "authentication_error: The request has no key, or its key is unknown, revoked or expired, or the key's owner left the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limit_error: The key is over its rate limit, where your deployment enforces one. Wait for the time given in Retry-After, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_error: An unexpected error occurred. Quote request_id when you contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "api_error: The session's history is still being indexed. Retry the request shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }