{ "openapi": "3.1.0", "info": { "title": "Everruns API", "description": "API for managing AI agents, sessions, messages, and events", "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "0.2.0" }, "servers": [ { "url": "https://app.everruns.com/api", "description": "Production API" } ], "paths": { "/v1/agents": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents - List all active agents", "operationId": "list_agents", "parameters": [ { "name": "search", "in": "query", "description": "Search by name or description (case-insensitive substring match).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "description": "Include archived agents. Deleted agents never appear in lists.", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "offset", "in": "query", "description": "Pagination offset (default 0).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "default": 0, "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Maximum items to return (default 20, max 100).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_WithUrls_AgentWithCounts" } } } }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "agents" ], "summary": "POST /v1/agents - Create a new agent", "operationId": "create_agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } }, "required": true }, "responses": { "201": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "400": { "description": "Input exceeds allowed limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/analyze": { "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/analyze - Run advisory checks against an agent shape", "description": "Runs built-in rules plus on-demand LLM analysis (knowledge/evaluation/agent-checks.md)\nand returns merged advisory findings. Requires the system utility LLM\nservice to be configured.", "operationId": "analyze_agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent analysis completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAnalysisResponse" } } } }, "400": { "description": "Utility LLM service not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Utility LLM provider rejected the analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/check-name": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/check-name", "description": "Returns whether an agent name is available for use. Optionally excludes\na specific agent ID (for edit forms where the agent's own name is valid).", "operationId": "check_agent_name", "parameters": [ { "name": "name", "in": "query", "description": "The agent name to check.", "required": true, "schema": { "type": "string" } }, { "name": "exclude_id", "in": "query", "description": "Optional agent ID to exclude (for edit forms where the current agent's own name is valid).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Name availability result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckAgentNameResponse" } } } }, "400": { "description": "Invalid exclude_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/config": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/config", "operationId": "agent_config", "responses": { "200": { "description": "Resource config for agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceConfigResponse" } } } } } } }, "/v1/agents/import": { "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/import - Import agent from file or built-in example", "description": "Two modes:\n1. **From example** — `POST /v1/agents/import?from-example={name}` (body ignored)\n2. **From file** — `POST /v1/agents/import` with a text body in Markdown/YAML/JSON\n\nFile mode accepts:\n- Markdown with YAML front matter (if starts with ---)\n- Pure YAML\n- Pure JSON\n- Plain text (treated as system prompt, name auto-generated)\n\nIf the file contains an `id` field and an agent with that ID already exists,\nthe agent is updated (upsert). Returns 201 on create, 200 on update.", "operationId": "import_agent", "parameters": [ { "name": "from-example", "in": "query", "description": "Import from a built-in example by name (e.g. `dad-jokes-agent`).\nWhen set, the request body is ignored.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Agent updated via import", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "201": { "description": "Agent imported successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "400": { "description": "Invalid format or input exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "High-risk capabilities require admin role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Example not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/preview": { "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/preview - Preview the final agent shape with capabilities applied", "description": "Returns the merged system prompt and all tools that would be available to the agent.\nThis is useful for previewing what the agent will look like before saving.", "operationId": "preview_agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent preview generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPreviewResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/{agent_id} - Get agent by ID or name", "description": "Accepts either an agent ID (e.g. `agent_01933b5a...`) or a\nname (e.g. `customer-support`). Names are resolved within the caller's org.", "operationId": "get_agent", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_AgentWithCounts" } } } }, "400": { "description": "Invalid agent ID" }, "404": { "description": "Agent not found" }, "500": { "description": "Internal server error" } } }, "put": { "tags": [ "agents" ], "summary": "PUT /v1/agents/{agent_id} - Create or update agent (upsert)", "description": "Accepts either an agent ID (e.g. `agent_01933b5a...`) or a\nname (e.g. `customer-support`). If the agent exists, update it; if not,\ncreate it. Returns 201 on create, 200 on update.", "operationId": "upsert_agent", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "201": { "description": "Agent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "agents" ], "summary": "DELETE /v1/agents/{agent_id} - Archive agent", "operationId": "delete_agent", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed, e.g., agt_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Agent archived successfully" }, "400": { "description": "Invalid agent ID" }, "404": { "description": "Agent not found" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "agents" ], "summary": "PATCH /v1/agents/{agent_id} - Update agent", "operationId": "update_agent", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed, e.g., agt_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "400": { "description": "Invalid agent ID or input exceeds allowed limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/copy": { "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/{agent_id}/copy - Copy an agent", "description": "Creates a new agent with the same configuration as the source agent.\nThe new agent's name will be \"{original name} (copy)\".", "operationId": "copy_agent", "parameters": [ { "name": "agent_id", "in": "path", "description": "Source agent ID to copy", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Agent copied successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "400": { "description": "Invalid agent ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Source agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/credentials": { "get": { "tags": [ "agents" ], "description": "List write-only MCP credential bindings for an agent. Responses contain metadata and configuration status, never credential values.", "operationId": "list_credentials", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credential binding metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_AgentCredentialBinding" } } } } } }, "post": { "tags": [ "agents" ], "description": "Declare a write-only credential binding for one MCP tool parameter. The secret value is provisioned separately.", "operationId": "create_credential_binding", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentCredentialBinding" } } }, "required": true }, "responses": { "200": { "description": "Credential binding created or updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCredentialBinding" } } } } } } }, "/v1/agents/{agent_id}/credentials/{binding_id}": { "put": { "tags": [ "agents" ], "description": "Encrypt and replace the write-only value for an agent credential binding.", "operationId": "set_credential_value", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } }, { "name": "binding_id", "in": "path", "description": "Credential binding ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAgentCredentialValueRequest" } } }, "required": true }, "responses": { "200": { "description": "Credential value replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCredentialBinding" } } } } } }, "delete": { "tags": [ "agents" ], "description": "Revoke an agent credential binding and permanently remove its encrypted value.", "operationId": "delete_credential_binding", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } }, { "name": "binding_id", "in": "path", "description": "Credential binding ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Credential binding revoked" }, "404": { "description": "Credential binding not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/endpoints": { "get": { "tags": [ "agent-endpoints" ], "description": "List ingress endpoints owned by an Agent.", "operationId": "list_agent_endpoints", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent endpoints", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AppChannel" } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "agent-endpoints" ], "description": "Create an ingress endpoint owned by an Agent.", "operationId": "create_agent_endpoint", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID or name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentEndpointRequest" } } }, "required": true }, "responses": { "201": { "description": "Endpoint created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppChannel" } } } }, "400": { "description": "Invalid endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/endpoints/{endpoint_id}": { "get": { "tags": [ "agent-endpoints" ], "description": "Get one ingress endpoint owned by an Agent.", "operationId": "get_agent_endpoint", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID or name", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppChannel" } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "agent-endpoints" ], "description": "Delete an ingress endpoint owned by an Agent.", "operationId": "delete_agent_endpoint", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID or name", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endpoint deleted" }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "agent-endpoints" ], "description": "Update an ingress endpoint owned by an Agent.", "operationId": "update_agent_endpoint", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID or name", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentEndpointRequest" } } }, "required": true }, "responses": { "200": { "description": "Endpoint updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppChannel" } } } }, "400": { "description": "Invalid endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/endpoints/{endpoint_id}/publish": { "post": { "tags": [ "agent-endpoints" ], "description": "Publish an Agent endpoint so it can accept ingress traffic.", "operationId": "publish_agent_endpoint", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID or name", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endpoint published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppChannel" } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/endpoints/{endpoint_id}/trigger": { "post": { "tags": [ "agent-endpoints" ], "description": "Run a published Agent schedule endpoint now.", "operationId": "trigger_agent_endpoint", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID or name", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endpoint triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerAgentEndpointOutput" } } } }, "400": { "description": "Endpoint cannot run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/endpoints/{endpoint_id}/unpublish": { "post": { "tags": [ "agent-endpoints" ], "description": "Unpublish an Agent endpoint so it no longer accepts ingress traffic.", "operationId": "unpublish_agent_endpoint", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID or name", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "Endpoint ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endpoint unpublished", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppChannel" } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/export": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/{agent_id}/export - Export agent in Markdown format with YAML front matter", "operationId": "export_agent", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed, e.g., agt_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent exported as Markdown", "content": { "text/markdown": {} } }, "400": { "description": "Invalid agent ID" }, "404": { "description": "Agent not found" }, "500": { "description": "Internal server error" } } } }, "/v1/agents/{agent_id}/exposures/resume": { "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/{agent_id}/exposures/resume - Let live endpoints serve again", "operationId": "resume_agent_exposures", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exposures resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/exposures/suspend": { "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/{agent_id}/exposures/suspend - Take every endpoint offline", "operationId": "suspend_agent_exposures", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exposures suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/health-checks": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/{agent_id}/health-checks - List recent health check runs", "operationId": "list_health_checks", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Health check runs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HealthCheckRun" } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/{agent_id}/health-checks - Trigger a behavioral health check", "operationId": "trigger_health_check", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Health check run started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckRun" } } } }, "400": { "description": "Health checks unavailable on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/health-checks/latest": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/{agent_id}/health-checks/latest - Latest run + stale flag", "operationId": "get_latest_health_check", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Latest health check run with stale-config flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestHealthCheckRun" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/health-checks/{run_id}": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/{agent_id}/health-checks/{run_id} - Get a health check run", "operationId": "get_health_check", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "description": "Health check run ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Health check run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckRun" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/mcp-attachments": { "get": { "tags": [ "agents" ], "description": "Lists the effective MCP attachments after capability, harness, and agent layers are merged. Connection state and permitted actions are resolved for the current caller.", "operationId": "list_agent_mcp_attachments", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Effective MCP attachments for the agent", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentMcpAttachment" } } } } }, "404": { "description": "Agent or harness not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/mcp-attachments/{name}/connection": { "delete": { "tags": [ "agents" ], "description": "Revokes the current caller's user connection or the agent identity's shared service connection for an effective MCP attachment. The attachment configuration remains unchanged.", "operationId": "revoke_agent_mcp_connection", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Effective MCP attachment name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "MCP connection revoked or already absent" }, "400": { "description": "Attachment does not use a connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent, attachment, or preset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/stats": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/{agent_id}/stats - Get aggregate usage stats for an agent", "operationId": "get_agent_stats", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent aggregate stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceStats" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/triggers": { "get": { "tags": [ "agent-triggers" ], "description": "List an agent's triggers. Set include_archived=true to also return archived triggers.", "operationId": "list_agent_triggers", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed)", "required": true, "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "description": "Include archived triggers (default false).", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Agent triggers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTrigger" } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "agent-triggers" ], "summary": "POST /v1/agents/{agent_id}/triggers", "operationId": "create_agent_trigger", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentTriggerRequest" } } }, "required": true }, "responses": { "201": { "description": "Trigger created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrigger" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/triggers/{trigger_id}": { "get": { "tags": [ "agent-triggers" ], "summary": "GET /v1/agents/{agent_id}/triggers/{trigger_id}", "operationId": "get_agent_trigger", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed)", "required": true, "schema": { "type": "string" } }, { "name": "trigger_id", "in": "path", "description": "Trigger ID (prefixed)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trigger", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrigger" } } } }, "404": { "description": "Trigger not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "agent-triggers" ], "summary": "DELETE /v1/agents/{agent_id}/triggers/{trigger_id}", "operationId": "delete_agent_trigger", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed)", "required": true, "schema": { "type": "string" } }, { "name": "trigger_id", "in": "path", "description": "Trigger ID (prefixed)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Trigger archived" }, "404": { "description": "Trigger not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "agent-triggers" ], "summary": "PATCH|PUT /v1/agents/{agent_id}/triggers/{trigger_id}", "operationId": "update_agent_trigger", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed)", "required": true, "schema": { "type": "string" } }, { "name": "trigger_id", "in": "path", "description": "Trigger ID (prefixed)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentTriggerRequest" } } }, "required": true }, "responses": { "200": { "description": "Trigger updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrigger" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Trigger not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/triggers/{trigger_id}/runs": { "get": { "tags": [ "agent-triggers" ], "description": "List the ten most recent durable execution outcomes for an agent trigger.", "operationId": "list_agent_trigger_runs", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed)", "required": true, "schema": { "type": "string" } }, { "name": "trigger_id", "in": "path", "description": "Trigger ID (prefixed)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent trigger outcomes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTriggerRun" } } } } }, "404": { "description": "Trigger not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/triggers/{trigger_id}/trigger": { "post": { "tags": [ "agent-triggers" ], "summary": "POST /v1/agents/{agent_id}/triggers/{trigger_id}/trigger", "operationId": "trigger_agent_trigger", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed)", "required": true, "schema": { "type": "string" } }, { "name": "trigger_id", "in": "path", "description": "Trigger ID (prefixed)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trigger fired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerAgentTriggerOutput" } } } }, "404": { "description": "Trigger not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/versions": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/{agent_id}/versions - List saved agent versions", "operationId": "list_agent_versions", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved agent versions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersion" } } } } }, "404": { "description": "Agent not found or agent_versions disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/{agent_id}/versions - Save the current agent configuration as a version", "operationId": "create_agent_version", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentVersionRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent version created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersion" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent not found or agent_versions disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/versions/default": { "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/{agent_id}/versions/default - Set the default version for an agent", "operationId": "set_default_agent_version", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultAgentVersionRequest" } } }, "required": true }, "responses": { "200": { "description": "Default version updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent or version not found, or agent_versions disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/versions/{from_version_id}/diff/{to_version_id}": { "get": { "tags": [ "agents" ], "summary": "GET /v1/agents/{agent_id}/versions/{from_version_id}/diff/{to_version_id} - Diff two agent versions", "operationId": "diff_agent_versions", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } }, { "name": "from_version_id", "in": "path", "description": "Base agent version ID", "required": true, "schema": { "$ref": "#/components/schemas/agentverId" } }, { "name": "to_version_id", "in": "path", "description": "Comparison agent version ID", "required": true, "schema": { "$ref": "#/components/schemas/agentverId" } } ], "responses": { "200": { "description": "Agent version diff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersionDiffResponse" } } } }, "404": { "description": "Agent or version not found, or agent_versions disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/versions/{version_id}/fork": { "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/{agent_id}/versions/{version_id}/fork - Create a new agent from a saved version", "operationId": "fork_agent_version", "parameters": [ { "name": "agent_id", "in": "path", "description": "Source agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } }, { "name": "version_id", "in": "path", "description": "Agent version ID", "required": true, "schema": { "$ref": "#/components/schemas/agentverId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkAgentVersionRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent fork created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent or version not found, or agent_versions disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/versions/{version_id}/rollback": { "post": { "tags": [ "agents" ], "summary": "POST /v1/agents/{agent_id}/versions/{version_id}/rollback - Restore an agent from a saved version", "operationId": "rollback_agent_version", "parameters": [ { "name": "agent_id", "in": "path", "description": "Agent ID (prefixed) or name", "required": true, "schema": { "type": "string" } }, { "name": "version_id", "in": "path", "description": "Agent version ID", "required": true, "schema": { "$ref": "#/components/schemas/agentverId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackAgentVersionRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent rolled back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Agent" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent or version not found, or agent_versions disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agents/{agent_id}/voice/sessions": { "post": { "tags": [ "voice" ], "description": "Create a voice session for a specific agent. Returns connection details for the realtime audio channel.", "operationId": "create_agent_voice_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCallRequest" } } }, "required": true }, "responses": { "201": { "description": "Agent session and realtime call created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceSessionResponse_VoiceCallResponse" } } } } } } }, "/v1/apps": { "get": { "tags": [ "apps" ], "description": "List archival App records. This endpoint is read-only and deprecated.", "operationId": "list_apps", "parameters": [ { "name": "search", "in": "query", "description": "Search by name or description (case-insensitive substring match).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "description": "Include archived apps. Deleted apps never appear in lists.", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "Archival list of Apps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WithUrls_App" } } } }, "500": { "description": "Internal server error" } }, "deprecated": true } }, "/v1/apps/{app_id}": { "get": { "tags": [ "apps" ], "description": "Get an archival App record. This endpoint is read-only and deprecated.", "operationId": "get_app", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Archival App record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_App" } } } }, "400": { "description": "Invalid App ID" }, "404": { "description": "App not found" }, "500": { "description": "Internal server error" } }, "deprecated": true } }, "/v1/apps/{app_id}/a2a/{channel_id}": { "post": { "tags": [ "apps" ], "summary": "POST /v1/apps/{app_id}/a2a/{channel_id}", "operationId": "invoke_a2a_legacy", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "description": "A2A channel ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "JSON-RPC 2.0 response. For message/send and tasks/* the body is a single JSON envelope; for message/stream the body is text/event-stream of JSON-RPC envelopes. tasks/get and tasks/cancel surface -32001 Task not found for unknown task ids." }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "App or channel not found, not published, or channel disabled (collapsed to a single generic 404 to prevent app-existence enumeration)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel A2A rate limit exceeded, or SSE connection limit reached for the org/session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app_id}/a2a/{channel_id}/.well-known/agent-card.json": { "get": { "tags": [ "apps" ], "summary": "GET /v1/apps/{app_id}/a2a/{channel_id}/.well-known/agent-card.json", "operationId": "agent_card_legacy", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "description": "A2A channel ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent Card JSON" }, "404": { "description": "App or channel not found / unpublished / disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app_id}/api/{channel_id}/sessions": { "post": { "tags": [ "apps" ], "summary": "POST /v1/apps/{app_id}/api/{channel_id}/sessions", "operationId": "create_session", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "description": "api_endpoint channel ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageBody" } } }, "required": true }, "responses": { "201": { "description": "Session created and message dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRef" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "App not published or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "App or channel not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app_id}/api/{channel_id}/sessions/{session_id}": { "get": { "tags": [ "apps" ], "summary": "GET /v1/apps/{app_id}/api/{channel_id}/sessions/{session_id}", "operationId": "get_session", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "description": "api_endpoint channel ID", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Derived status and the agent's completed messages (no raw tool detail)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatus" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "App not published or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Channel or session not found / not owned by this channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app_id}/api/{channel_id}/sessions/{session_id}/cancel": { "post": { "tags": [ "apps" ], "summary": "POST /v1/apps/{app_id}/api/{channel_id}/sessions/{session_id}/cancel", "operationId": "cancel_session", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "description": "api_endpoint channel ID", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "In-flight turn canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRef" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "App not published or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Channel or session not found / not owned by this channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app_id}/api/{channel_id}/sessions/{session_id}/messages": { "post": { "tags": [ "apps" ], "summary": "POST /v1/apps/{app_id}/api/{channel_id}/sessions/{session_id}/messages", "operationId": "post_message", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "description": "api_endpoint channel ID", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageBody" } } }, "required": true }, "responses": { "202": { "description": "Follow-up message dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRef" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "App not published or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Channel or session not found / not owned by this channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/apps/{app_id}/fcp": { "get": { "tags": [ "apps" ], "summary": "`GET /v1/apps/{app_id}/fcp` — handshake. Always returns the same\ngeneric 404 body for unknown apps so the endpoint cannot be used to\nprobe which app ids are real.", "operationId": "handshake", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Markdown handshake describing the FCP endpoint and how to authenticate. Always `text/markdown`.", "content": { "text/markdown": {} } }, "404": { "description": "No FCP endpoint at this URL. Single sanitized body covers unknown apps, unpublished apps, apps without an FCP channel, and disabled FCP channels — operator state is never disclosed.", "content": { "text/markdown": {} } }, "429": { "description": "Per-channel FCP rate limit exceeded. `Retry-After: 60` header is set.", "content": { "text/markdown": {} } } } }, "post": { "tags": [ "apps" ], "summary": "`POST /v1/apps/{app_id}/fcp` — text-in, text-out.", "operationId": "message_legacy", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Plain UTF-8 text, or `application/json` of shape `{\"message\": \"...\"}`. Maximum 256 KiB.", "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Agent reply as Markdown. The `Set-Cookie: fcp_session=...` header is emitted so subsequent POSTs can resume the same conversation.", "content": { "text/markdown": {} } }, "400": { "description": "Malformed body. Distinct messages for empty body, non-UTF-8 bytes, and JSON that did not parse into the expected shape — each Markdown body points back at the handshake.", "content": { "text/markdown": {} } }, "401": { "description": "Token required but missing or wrong. Markdown body explains both accepted headers (`Authorization: Bearer` and `X-Everruns-FCP-Token`) and points at the handshake.", "content": { "text/markdown": {} } }, "404": { "description": "Same generic 404 as the handshake — operator state is never disclosed.", "content": { "text/markdown": {} } }, "410": { "description": "FCP session expired. Body tells the client to drop the `fcp_session` cookie and POST again.", "content": { "text/markdown": {} } }, "413": { "description": "Body exceeds 256 KiB.", "content": { "text/markdown": {} } }, "429": { "description": "Per-channel FCP rate limit exceeded. `Retry-After: 60` header is set.", "content": { "text/markdown": {} } }, "504": { "description": "Agent did not reply within the configured timeout. The same `fcp_session` cookie is set so the client can retry the same conversation.", "content": { "text/markdown": {} } } } } }, "/v1/apps/{app_id}/webhooks/{channel_id}": { "post": { "tags": [ "apps" ], "description": "Invoke a webhook channel for a published App. The body is forwarded to the agent as a message.", "operationId": "invoke_webhook_legacy", "parameters": [ { "name": "app_id", "in": "path", "description": "App ID", "required": true, "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "description": "Webhook channel ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "required": true }, "responses": { "202": { "description": "Webhook accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvocationResponse" } } } }, "401": { "description": "Invalid or missing webhook token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "App or channel not found, not published, or channel disabled (collapsed to a single generic 404 to prevent app-existence enumeration)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/capabilities": { "get": { "tags": [ "capabilities" ], "summary": "GET /v1/capabilities - List available capabilities with pagination", "operationId": "list_capabilities", "parameters": [ { "name": "search", "in": "query", "description": "Search by name/description", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Pagination offset (default: 0)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Page size (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "include_retired", "in": "query", "description": "Include retired capabilities (default: false)", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated list of capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_WithUrls_CapabilityInfo" } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "capabilities" ], "summary": "POST /v1/capabilities - Create a persisted declarative capability.", "operationId": "create_declarative_capability", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeclarativeCapabilityRequest" } } }, "required": true }, "responses": { "201": { "description": "Declarative capability created. Response id uses cap_<32-hex>; capability_id uses declarative:.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_DeclarativeCapability" } } } }, "400": { "description": "Invalid declarative capability definition, name, limits, file mount, skill, or MCP server configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A declarative capability with the same unique name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/capabilities/declarative": { "get": { "tags": [ "capabilities" ], "summary": "GET /v1/capabilities/declarative - List persisted declarative resources.", "operationId": "list_declarative_capabilities", "parameters": [ { "name": "search", "in": "query", "description": "Search by unique name, display name, or description", "required": false, "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "description": "Include archived declarative capabilities", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Persisted declarative capability resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WithUrls_DeclarativeCapability" } } } } } } }, "/v1/capabilities/declarative/config": { "get": { "tags": [ "capabilities" ], "summary": "GET /v1/capabilities/declarative/config", "operationId": "declarative_capabilities_config", "responses": { "200": { "description": "Resource config for declarative capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceConfigResponse" } } } } } } }, "/v1/capabilities/declarative/{capability_id}": { "get": { "tags": [ "capabilities" ], "summary": "GET /v1/capabilities/declarative/{capability_id} - Get a declarative resource.", "operationId": "get_declarative_capability", "parameters": [ { "name": "capability_id", "in": "path", "description": "Public declarative capability resource ID, e.g. cap_01933b5a000070008000000000000001", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Declarative capability resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_DeclarativeCapability" } } } }, "404": { "description": "Declarative capability not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "capabilities" ], "summary": "DELETE /v1/capabilities/declarative/{capability_id} - Archive a declarative resource.", "operationId": "delete_declarative_capability", "parameters": [ { "name": "capability_id", "in": "path", "description": "Public declarative capability resource ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Declarative capability archived" }, "404": { "description": "Declarative capability not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "capabilities" ], "summary": "PATCH /v1/capabilities/declarative/{capability_id} - Update a declarative resource.", "operationId": "update_declarative_capability", "parameters": [ { "name": "capability_id", "in": "path", "description": "Public declarative capability resource ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDeclarativeCapabilityRequest" } } }, "required": true }, "responses": { "200": { "description": "Declarative capability updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_DeclarativeCapability" } } } }, "400": { "description": "Invalid update payload or declarative capability definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A declarative capability with the same unique name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/capabilities/declarative/{capability_id}/delete": { "post": { "tags": [ "capabilities" ], "summary": "POST /v1/capabilities/declarative/{capability_id}/delete - Permanently delete archived resource.", "operationId": "destroy_declarative_capability", "parameters": [ { "name": "capability_id", "in": "path", "description": "Public declarative capability resource ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Archived declarative capability permanently deleted" }, "404": { "description": "Declarative capability not found or not archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/capabilities/guardrails/dry-run": { "post": { "tags": [ "capabilities" ], "summary": "POST /v1/capabilities/guardrails/dry-run - Evaluate guardrail checks against sample text.", "operationId": "dry_run_guardrails", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailsDryRunRequest" } } }, "required": true }, "responses": { "200": { "description": "Triggered checks for the sample content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailsDryRunResponse" } } } }, "400": { "description": "Invalid guardrails config, stage, or oversized text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/capabilities/guardrails/examples": { "get": { "tags": [ "capabilities" ], "summary": "GET /v1/capabilities/guardrails/examples - List adoptable guardrail presets.", "operationId": "list_guardrail_examples", "responses": { "200": { "description": "Adoptable guardrail presets with trust metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailExamplesResponse" } } } } } } }, "/v1/capabilities/{capability_id}": { "get": { "tags": [ "capabilities" ], "summary": "GET /v1/capabilities/{capability_id} - Get a specific capability", "operationId": "get_capability", "parameters": [ { "name": "capability_id", "in": "path", "description": "Capability ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Capability found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_CapabilityInfo" } } } }, "404": { "description": "Capability not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/circuit-breakers": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/circuit-breakers - List circuit breakers", "operationId": "list_circuit_breakers", "responses": { "200": { "description": "List of circuit breakers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CircuitBreakersListResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/circuit-breakers/{key}": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/circuit-breakers/:key - Get a single circuit breaker", "operationId": "get_circuit_breaker", "parameters": [ { "name": "key", "in": "path", "description": "Circuit breaker key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Circuit breaker details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CircuitBreakerResponse" } } } }, "404": { "description": "Circuit breaker not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "durable" ], "summary": "DELETE /v1/durable/circuit-breakers/:key - Delete/reset a circuit breaker", "operationId": "delete_circuit_breaker", "parameters": [ { "name": "key", "in": "path", "description": "Circuit breaker key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Circuit breaker deleted" }, "404": { "description": "Circuit breaker not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/circuit-breakers/{key}/close": { "post": { "tags": [ "durable" ], "summary": "POST /v1/durable/circuit-breakers/:key/close - Force close a circuit breaker", "operationId": "force_close_circuit_breaker", "parameters": [ { "name": "key", "in": "path", "description": "Circuit breaker key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Circuit breaker closed" }, "404": { "description": "Circuit breaker not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/circuit-breakers/{key}/open": { "post": { "tags": [ "durable" ], "summary": "POST /v1/durable/circuit-breakers/:key/open - Force open a circuit breaker", "operationId": "force_open_circuit_breaker", "parameters": [ { "name": "key", "in": "path", "description": "Circuit breaker key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Circuit breaker opened" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/config": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/config - Durable policy results for UI gating.", "operationId": "durable_config", "responses": { "200": { "description": "Resource config for durable surfaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceConfigResponse" } } } } } } }, "/v1/durable/dlq": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/dlq - List dead letter queue entries", "operationId": "list_dlq", "parameters": [ { "name": "workflow_id", "in": "query", "description": "Filter by workflow ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "activity_type", "in": "query", "description": "Filter by activity type", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Pagination limit", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of DLQ entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DlqListResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/dlq/{dlq_id}/retry": { "post": { "tags": [ "durable" ], "summary": "POST /v1/durable/dlq/:dlq_id/retry - Retry a DLQ entry", "operationId": "retry_dlq", "parameters": [ { "name": "dlq_id", "in": "path", "description": "DLQ entry ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task requeued", "content": { "text/plain": { "schema": { "type": "string", "format": "uuid" } } } }, "404": { "description": "DLQ entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/executions/{execution_id}": { "get": { "tags": [ "durable-schedules" ], "summary": "GET /v1/durable/executions/:execution_id - Get execution details", "operationId": "get_execution", "parameters": [ { "name": "execution_id", "in": "path", "description": "Execution ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Execution details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleExecutionResponse" } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Execution not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/health": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/health - Get system health", "operationId": "get_health", "responses": { "200": { "description": "System health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/metrics/timeseries": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/metrics/timeseries - Get metrics time series", "operationId": "get_metrics_timeseries", "responses": { "200": { "description": "Metrics time series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsTimeSeriesResponse" } } } } } } }, "/v1/durable/schedules": { "get": { "tags": [ "durable-schedules" ], "summary": "GET /v1/durable/schedules - List schedules", "operationId": "list_schedules", "parameters": [ { "name": "enabled", "in": "query", "description": "Filter by enabled status", "required": false, "schema": { "type": "boolean" } }, { "name": "target_type", "in": "query", "description": "Filter by target type", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Pagination limit", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of schedules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchedulesListResponse" } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "durable-schedules" ], "summary": "POST /v1/durable/schedules - Create a new schedule", "operationId": "create_schedule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRequest" } } }, "required": true }, "responses": { "201": { "description": "Schedule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required" }, "409": { "description": "Schedule name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/schedules/{schedule_id}": { "get": { "tags": [ "durable-schedules" ], "summary": "GET /v1/durable/schedules/:schedule_id - Get schedule details", "operationId": "get_schedule", "parameters": [ { "name": "schedule_id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Schedule details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "durable-schedules" ], "summary": "DELETE /v1/durable/schedules/:schedule_id - Delete schedule", "operationId": "delete_schedule", "parameters": [ { "name": "schedule_id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Schedule deleted" }, "401": { "description": "Authentication required" }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "durable-schedules" ], "summary": "PATCH /v1/durable/schedules/:schedule_id - Update schedule", "operationId": "update_schedule", "parameters": [ { "name": "schedule_id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleRequest" } } }, "required": true }, "responses": { "200": { "description": "Schedule updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/schedules/{schedule_id}/executions": { "get": { "tags": [ "durable-schedules" ], "summary": "GET /v1/durable/schedules/:schedule_id/executions - List schedule executions", "operationId": "list_schedule_executions", "parameters": [ { "name": "schedule_id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Pagination limit", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of executions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleExecutionsListResponse" } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/schedules/{schedule_id}/pause": { "post": { "tags": [ "durable-schedules" ], "summary": "POST /v1/durable/schedules/:schedule_id/pause - Pause schedule", "operationId": "pause_schedule", "parameters": [ { "name": "schedule_id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Schedule paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/schedules/{schedule_id}/resume": { "post": { "tags": [ "durable-schedules" ], "summary": "POST /v1/durable/schedules/:schedule_id/resume - Resume schedule", "operationId": "resume_schedule", "parameters": [ { "name": "schedule_id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Schedule resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/schedules/{schedule_id}/stats": { "get": { "tags": [ "durable-schedules" ], "summary": "GET /v1/durable/schedules/:schedule_id/stats - Get schedule statistics", "operationId": "get_schedule_stats", "parameters": [ { "name": "schedule_id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Schedule statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleStatsResponse" } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/schedules/{schedule_id}/trigger": { "post": { "tags": [ "durable-schedules" ], "summary": "POST /v1/durable/schedules/:schedule_id/trigger - Manually trigger schedule", "operationId": "trigger_schedule", "parameters": [ { "name": "schedule_id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Schedule triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Schedule not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/sse": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/sse - Stream global durable state (SSE)", "description": "Establishes a Server-Sent Events (SSE) connection for real-time durable system monitoring.\n\n## Connection Lifecycle Events\n\n- **connected**: Sent immediately when the stream is established.\n- **snapshot**: Sent when system state changes (health, workers, workflows, tasks, DLQ, circuit breakers).\n- **disconnecting**: Sent before the server closes the connection for graceful cycling.\n Data: `{\"reason\":\"connection_cycle\",\"retry_ms\":1000}`\n\n## Connection Cycling\n\nConnections are automatically cycled every 10 minutes. Before closing, the server sends\na `disconnecting` event so clients can reconnect seamlessly.\n\n## Retry Hints\n\nEach SSE event includes a `retry:` field (in milliseconds) that hints reconnection timing:\n- During active updates: 1000ms\n- During idle periods: increases with backoff up to 20000ms\n- After `disconnecting` event: 1000ms", "operationId": "stream_durable_sse", "responses": { "200": { "description": "SSE event stream with 'connected', 'snapshot', and 'disconnecting' events", "content": { "text/event-stream": {} } }, "503": { "description": "Durable store not available" } } } }, "/v1/durable/tasks": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/tasks - List tasks", "operationId": "list_tasks", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string" } }, { "name": "activity_type", "in": "query", "description": "Filter by activity type", "required": false, "schema": { "type": "string" } }, { "name": "workflow_id", "in": "query", "description": "Filter by workflow ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Pagination limit", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksListResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "durable" ], "summary": "POST /v1/durable/tasks - Enqueue a standalone task (generic queue)", "operationId": "enqueue_task", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueTaskRequest" } } }, "required": true }, "responses": { "201": { "description": "Task enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueTaskResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/workers": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/workers - List workers", "operationId": "list_workers", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string" } }, { "name": "worker_group", "in": "query", "description": "Filter by worker group", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of workers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkersListResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/workers/{worker_id}/drain": { "post": { "tags": [ "durable" ], "summary": "POST /v1/durable/workers/:worker_id/drain - Drain a worker", "operationId": "drain_worker", "parameters": [ { "name": "worker_id", "in": "path", "description": "Worker ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Worker drained" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/workers/{worker_id}/resume": { "post": { "tags": [ "durable" ], "summary": "POST /v1/durable/workers/:worker_id/resume - Resume a draining worker", "operationId": "resume_worker", "parameters": [ { "name": "worker_id", "in": "path", "description": "Worker ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Worker resumed" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/workflows": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/workflows - List workflows", "operationId": "list_workflows", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string" } }, { "name": "workflow_type", "in": "query", "description": "Filter by workflow type", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Pagination limit", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of workflows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowsListResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/workflows/{workflow_id}": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/workflows/:workflow_id - Get workflow details", "operationId": "get_workflow", "parameters": [ { "name": "workflow_id", "in": "path", "description": "Workflow ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workflow details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } } }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/workflows/{workflow_id}/cancel": { "post": { "tags": [ "durable" ], "summary": "POST /v1/durable/workflows/:workflow_id/cancel - Cancel a workflow", "operationId": "cancel_workflow", "parameters": [ { "name": "workflow_id", "in": "path", "description": "Workflow ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workflow cancelled" }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/workflows/{workflow_id}/events": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/workflows/:workflow_id/events - Get workflow events", "operationId": "get_workflow_events", "parameters": [ { "name": "workflow_id", "in": "path", "description": "Workflow ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of workflow events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowEventsListResponse" } } } }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/workflows/{workflow_id}/signal": { "post": { "tags": [ "durable" ], "summary": "POST /v1/durable/workflows/:workflow_id/signal - Send signal to workflow", "operationId": "send_signal", "parameters": [ { "name": "workflow_id", "in": "path", "description": "Workflow ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSignalRequest" } } }, "required": true }, "responses": { "200": { "description": "Signal sent" }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/durable/workflows/{workflow_id}/sse": { "get": { "tags": [ "durable" ], "summary": "GET /v1/durable/workflows/:workflow_id/sse - Stream workflow state (SSE)", "description": "Establishes a Server-Sent Events (SSE) connection for real-time workflow monitoring.\n\n## Connection Lifecycle Events\n\n- **connected**: Sent immediately when the stream is established.\n- **snapshot**: Sent when workflow state or events change.\n- **disconnecting**: Sent before the server closes the connection for graceful cycling.\n Data: `{\"reason\":\"connection_cycle\",\"retry_ms\":1000}`\n\n## Connection Cycling\n\nConnections are automatically cycled every 10 minutes. Before closing, the server sends\na `disconnecting` event so clients can reconnect seamlessly.\n\n## Retry Hints\n\nEach SSE event includes a `retry:` field (in milliseconds) that hints reconnection timing.", "operationId": "stream_workflow_sse", "parameters": [ { "name": "workflow_id", "in": "path", "description": "Workflow ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SSE event stream with 'connected', 'snapshot', and 'disconnecting' events", "content": { "text/event-stream": {} } }, "404": { "description": "Workflow not found" }, "503": { "description": "Durable store not available" } } } }, "/v1/e/{channel_id}/a2a": { "post": { "tags": [ "apps" ], "description": "Invoke a published A2A endpoint with JSON-RPC 2.0. Authentication follows the endpoint channel configuration.", "operationId": "invoke_a2a_endpoint", "parameters": [ { "name": "channel_id", "in": "path", "description": "A2A endpoint channel ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "JSON-RPC response or event stream" }, "400": { "description": "Invalid JSON-RPC request" }, "401": { "description": "Missing or invalid endpoint credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Endpoint not found, app not published, or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel or SSE connection limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/e/{channel_id}/a2a/.well-known/agent-card.json": { "get": { "tags": [ "apps" ], "description": "Get the public Agent Card for a published A2A endpoint.", "operationId": "agent_card_endpoint", "parameters": [ { "name": "channel_id", "in": "path", "description": "A2A endpoint channel ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent Card JSON" }, "404": { "description": "Endpoint not found, app not published, or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/e/{channel_id}/fcp": { "post": { "tags": [ "apps" ], "description": "Send a message to a published FCP endpoint. Authenticate with Authorization: Bearer or X-Everruns-FCP-Token when the endpoint requires a token.", "operationId": "message_endpoint", "parameters": [ { "name": "channel_id", "in": "path", "description": "FCP endpoint channel ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Plain UTF-8 text or JSON with a message field. Maximum 256 KiB.", "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Agent reply as Markdown", "content": { "text/markdown": {} } }, "400": { "description": "Malformed or empty message", "content": { "text/markdown": {} } }, "401": { "description": "Missing or invalid FCP token", "content": { "text/markdown": {} } }, "404": { "description": "Endpoint not found, app not published, or channel disabled", "content": { "text/markdown": {} } }, "410": { "description": "FCP session expired", "content": { "text/markdown": {} } }, "413": { "description": "Body exceeds 256 KiB", "content": { "text/markdown": {} } }, "429": { "description": "Per-channel FCP rate limit exceeded", "content": { "text/markdown": {} } }, "504": { "description": "Agent response timeout", "content": { "text/markdown": {} } } } } }, "/v1/e/{channel_id}/sessions": { "post": { "tags": [ "apps" ], "description": "Create a session through an api_endpoint channel. Authenticate with the channel bearer key or configured endpoint auth.", "operationId": "create_session_endpoint", "parameters": [ { "name": "channel_id", "in": "path", "description": "api_endpoint channel ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageBody" } } }, "required": true }, "responses": { "201": { "description": "Session created and message dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRef" } } } }, "401": { "description": "Missing or invalid endpoint credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "App not published or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/e/{channel_id}/sessions/{session_id}": { "get": { "tags": [ "apps" ], "description": "Get derived status and completed agent messages for a session owned by an api_endpoint channel.", "operationId": "get_session_endpoint", "parameters": [ { "name": "channel_id", "in": "path", "description": "api_endpoint channel ID", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Derived session status and completed agent messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatus" } } } }, "401": { "description": "Missing or invalid endpoint credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "App not published or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Endpoint or session not found, or session not owned by this channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/e/{channel_id}/sessions/{session_id}/cancel": { "post": { "tags": [ "apps" ], "description": "Cancel the active turn for a session owned by an api_endpoint channel.", "operationId": "cancel_session_endpoint", "parameters": [ { "name": "channel_id", "in": "path", "description": "api_endpoint channel ID", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "In-flight turn canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRef" } } } }, "401": { "description": "Missing or invalid endpoint credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "App not published or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Endpoint or session not found, or session not owned by this channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/e/{channel_id}/sessions/{session_id}/messages": { "post": { "tags": [ "apps" ], "description": "Post a follow-up message to a session owned by an api_endpoint channel.", "operationId": "post_message_endpoint", "parameters": [ { "name": "channel_id", "in": "path", "description": "api_endpoint channel ID", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageBody" } } }, "required": true }, "responses": { "202": { "description": "Follow-up message dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRef" } } } }, "401": { "description": "Missing or invalid endpoint credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "App not published or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Endpoint or session not found, or session not owned by this channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/e/{channel_id}/webhook": { "post": { "tags": [ "apps" ], "description": "Invoke a published webhook endpoint. Authenticate with its channel token in Authorization: Bearer or X-Everruns-Webhook-Token.", "operationId": "invoke_webhook_endpoint", "parameters": [ { "name": "channel_id", "in": "path", "description": "Webhook endpoint channel ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "required": true }, "responses": { "202": { "description": "Webhook accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvocationResponse" } } } }, "401": { "description": "Invalid or missing webhook token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Endpoint not found, app not published, or channel disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Per-channel rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/environment-targets": { "get": { "tags": [ "environments" ], "description": "List the environment targets this deployment can offer, with the capabilities each one actually has.", "operationId": "list_environment_targets", "responses": { "200": { "description": "Available environment targets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentTargetsResponse" } } } } } } }, "/v1/files": { "get": { "tags": [ "Files" ], "summary": "List uploaded files, newest first.", "operationId": "list_files", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of files to return.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List files", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileInfo" } } } } } } }, "post": { "tags": [ "Files" ], "summary": "Upload a PDF file for use as model input.", "operationId": "upload_file", "parameters": [ { "name": "session_id", "in": "query", "description": "Optional session to attribute the upload to.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "string" } } }, "required": true }, "responses": { "201": { "description": "File uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } }, "400": { "description": "Invalid file" }, "413": { "description": "File too large" } } } }, "/v1/files/{file_id}": { "get": { "tags": [ "Files" ], "summary": "Download a stored file's bytes.", "operationId": "get_file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes" } } }, "delete": { "tags": [ "Files" ], "summary": "Delete a stored file.", "operationId": "delete_file", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File deleted" } } } }, "/v1/harness-examples": { "get": { "tags": [ "harness-examples" ], "summary": "GET /v1/harness-examples — list all available harness examples.", "operationId": "list_examples", "responses": { "200": { "description": "List of harness examples", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HarnessExample" } } } } } } } }, "/v1/harnesses": { "get": { "tags": [ "harnesses" ], "summary": "GET /v1/harnesses", "operationId": "list_harnesses", "parameters": [ { "name": "search", "in": "query", "description": "Search by name or description (case-insensitive substring match).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "description": "Include archived harnesses. Deleted harnesses never appear in lists.", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "List of harnesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WithUrls_ResourceWithCounts_Harness" } } } }, "403": { "description": "Forbidden" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "harnesses" ], "summary": "POST /v1/harnesses", "operationId": "create_harness", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHarnessRequest" } } }, "required": true }, "responses": { "201": { "description": "Harness created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Harness" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/harnesses/check-name": { "get": { "tags": [ "harnesses" ], "summary": "GET /v1/harnesses/check-name", "description": "Returns whether a harness name is available for use. Optionally excludes\na specific harness ID (for edit forms where the harness's own name is valid).", "operationId": "check_harness_name", "parameters": [ { "name": "name", "in": "query", "description": "The harness name to check.", "required": true, "schema": { "type": "string" } }, { "name": "exclude_id", "in": "query", "description": "Optional harness ID to exclude (for edit forms where the current harness's own name is valid).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Name availability result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckNameResponse" } } } }, "400": { "description": "Invalid exclude_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/harnesses/config": { "get": { "tags": [ "harnesses" ], "summary": "GET /v1/harnesses/config", "description": "Returns which harness policies the caller satisfies.\nUI uses this to show/hide controls (e.g. delete button).", "operationId": "harness_config", "responses": { "200": { "description": "Resource config for harnesses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceConfigResponse" } } } } } } }, "/v1/harnesses/import": { "post": { "tags": [ "harnesses" ], "summary": "POST /v1/harnesses/import - Adopt a harness example as a regular org-owned harness.", "description": "Creates a normal harness (`is_built_in = false`) from a code-defined\nexample. The new harness inherits from the org's `generic` harness by\nname — no UUIDs are hardcoded. Capabilities and other config flow through\nthe same validation paths as `POST /v1/harnesses`.\n\nReturns 201 on creation. If the example name collides with an existing\nharness in the org, a random alphanumeric suffix is appended (parity with\nagent example import).", "operationId": "import_harness", "parameters": [ { "name": "from-example", "in": "query", "description": "Import from a built-in harness example by name (e.g. `data-analyst`).\nRequired: the only currently supported import mode is from-example.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Harness adopted from example", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Harness" } } } }, "400": { "description": "Invalid input or missing capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Example not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/harnesses/preview": { "post": { "tags": [ "harnesses" ], "summary": "POST /v1/harnesses/preview", "operationId": "preview_harness", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewHarnessRequest" } } }, "required": true }, "responses": { "200": { "description": "Harness preview generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessPreviewResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/harnesses/{harness_id}": { "get": { "tags": [ "harnesses" ], "summary": "GET /v1/harnesses/{harness_id}", "description": "Accepts either a harness ID (e.g. `harness_01933b5a...`) or a\nname (e.g. `generic`). The virtual name `default` resolves to the org's\nconfigured default harness. Names are resolved within the caller's org.", "operationId": "get_harness", "parameters": [ { "name": "harness_id", "in": "path", "description": "Harness ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Harness found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_ResourceWithCounts_Harness" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Harness not found" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "harnesses" ], "summary": "DELETE /v1/harnesses/{harness_id}", "operationId": "delete_harness", "parameters": [ { "name": "harness_id", "in": "path", "description": "Harness ID (prefixed)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Harness archived" }, "400": { "description": "Invalid harness ID" }, "403": { "description": "Forbidden" }, "404": { "description": "Harness not found" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "harnesses" ], "summary": "PATCH /v1/harnesses/{harness_id}", "operationId": "update_harness", "parameters": [ { "name": "harness_id", "in": "path", "description": "Harness ID (prefixed)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHarnessRequest" } } }, "required": true }, "responses": { "200": { "description": "Harness updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Harness" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Harness not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/harnesses/{harness_id}/copy": { "post": { "tags": [ "harnesses" ], "summary": "POST /v1/harnesses/{harness_id}/copy - Copy a harness", "description": "Creates a new harness with the same configuration as the source harness.\nThe new harness's name will be \"{original name} (copy)\".", "operationId": "copy_harness", "parameters": [ { "name": "harness_id", "in": "path", "description": "Source harness ID to copy", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Harness copied successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Harness" } } } }, "400": { "description": "Invalid harness ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Source harness not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/harnesses/{harness_id}/stats": { "get": { "tags": [ "harnesses" ], "summary": "GET /v1/harnesses/{harness_id}/stats - Get aggregate usage stats for a harness", "operationId": "get_harness_stats", "parameters": [ { "name": "harness_id", "in": "path", "description": "Harness ID (prefixed) or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Harness aggregate stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceStats" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Harness not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/images": { "get": { "tags": [ "images" ], "summary": "GET /v1/images - List images", "operationId": "list_images", "parameters": [ { "name": "limit", "in": "query", "description": "Max items to return (default 50)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Items to skip", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "List of images", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ImageInfo" } } } } }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "images" ], "summary": "POST /v1/images - Upload an image", "operationId": "upload_image", "parameters": [ { "name": "session_id", "in": "query", "description": "Optional: session ID stored as metadata for tracking (not required for upload)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Multipart form data with 'file' field", "content": { "multipart/form-data": { "schema": { "type": "string" } } }, "required": true }, "responses": { "201": { "description": "Image uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageUploadResponse" } } } }, "400": { "description": "Invalid request (bad format, size exceeded, etc.)" }, "500": { "description": "Internal server error" } } } }, "/v1/images/{image_id}": { "get": { "tags": [ "images" ], "summary": "GET /v1/images/{image_id} - Get image (returns binary data)", "operationId": "get_image", "parameters": [ { "name": "image_id", "in": "path", "description": "Image ID (prefixed, e.g., img_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Image binary data", "content": { "image/*": {} } }, "400": { "description": "Invalid image ID" }, "404": { "description": "Image not found" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "images" ], "summary": "DELETE /v1/images/{image_id} - Delete an image", "operationId": "delete_image", "parameters": [ { "name": "image_id", "in": "path", "description": "Image ID (prefixed, e.g., img_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Image deleted" }, "400": { "description": "Invalid image ID" }, "404": { "description": "Image not found" }, "500": { "description": "Internal server error" } } } }, "/v1/images/{image_id}/thumbnail": { "get": { "tags": [ "images" ], "summary": "GET /v1/images/{image_id}/thumbnail - Get image thumbnail", "operationId": "get_thumbnail", "parameters": [ { "name": "image_id", "in": "path", "description": "Image ID (prefixed, e.g., img_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thumbnail binary data", "content": { "image/jpeg": {} } }, "400": { "description": "Invalid image ID" }, "404": { "description": "Image not found or no thumbnail" }, "500": { "description": "Internal server error" } } } }, "/v1/knowledge-bases": { "get": { "tags": [ "knowledge_bases" ], "description": "List knowledge bases.", "operationId": "list_kbs", "parameters": [ { "name": "search", "in": "query", "description": "Substring filter applied to knowledge-base name and description.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "description": "When `true`, also returns archived knowledge bases.", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "List knowledge bases", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_KnowledgeBaseResponse" } } } } } }, "post": { "tags": [ "knowledge_bases" ], "description": "Create a new knowledge base.", "operationId": "create_kb", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeBaseRequest" } } }, "required": true }, "responses": { "201": { "description": "Knowledge base created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Duplicate knowledge base name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-bases/{kb_id}": { "get": { "tags": [ "knowledge_bases" ], "description": "Get a knowledge base by ID.", "operationId": "get_kb", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Knowledge base found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponse" } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "knowledge_bases" ], "description": "Delete a knowledge base.", "operationId": "delete_kb", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Knowledge base archived" }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "knowledge_bases" ], "description": "Update a knowledge base. Only provided fields are modified.", "operationId": "update_kb", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeBaseRequest" } } }, "required": true }, "responses": { "200": { "description": "Knowledge base updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Duplicate knowledge base name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-bases/{kb_id}/entries": { "get": { "tags": [ "knowledge_bases" ], "description": "List knowledge base entries.", "operationId": "list_entries", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Substring filter applied to entry title and body.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "kind", "in": "query", "description": "Discriminator selecting the variant of this resource. One of `note`,\n`table`, `business`, `query`, `runbook`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "List entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_KnowledgeEntryResponse" } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "knowledge_bases" ], "description": "Create a new knowledge base entry.", "operationId": "create_entry", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeEntryRequest" } } }, "required": true }, "responses": { "201": { "description": "Entry created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeEntryResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-bases/{kb_id}/entries/{entry_id}": { "get": { "tags": [ "knowledge_bases" ], "description": "Get a knowledge base entry by ID.", "operationId": "get_entry", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "Entry ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entry found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeEntryResponse" } } } }, "404": { "description": "Entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "knowledge_bases" ], "description": "Delete a knowledge base entry.", "operationId": "delete_entry", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "Entry ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Entry deleted" }, "404": { "description": "Entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "knowledge_bases" ], "description": "Update a knowledge base entry. Only provided fields are modified.", "operationId": "update_entry", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "Entry ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeEntryRequest" } } }, "required": true }, "responses": { "200": { "description": "Entry updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeEntryResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-bases/{kb_id}/okf_export": { "get": { "tags": [ "knowledge_bases" ], "description": "Export a knowledge base as an Open Knowledge Format (OKF) bundle (a gzipped tarball of markdown files with YAML frontmatter). See knowledge/runtime-resources/okf-adoption.md.", "operationId": "export_okf", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OKF bundle (.tar.gz)", "content": { "application/gzip": {} } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-bases/{kb_id}/okf_import": { "post": { "tags": [ "knowledge_bases" ], "description": "Import an Open Knowledge Format (OKF) bundle into a knowledge base. Idempotent: re-importing converges entries without duplicates. See knowledge/runtime-resources/okf-adoption.md.", "operationId": "import_okf", "parameters": [ { "name": "kb_id", "in": "path", "description": "Knowledge base ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportOkfBundleRequest" } } }, "required": true }, "responses": { "200": { "description": "Import summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkfImportSummary" } } } }, "400": { "description": "Invalid bundle or input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-indexes": { "get": { "tags": [ "knowledge_indexes" ], "description": "List knowledge indexes.", "operationId": "list_indexes", "parameters": [ { "name": "search", "in": "query", "description": "Substring filter applied to index name and description.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "description": "When `true`, also returns archived knowledge indexes.", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "List knowledge indexes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_KnowledgeIndexResponse" } } } } } }, "post": { "tags": [ "knowledge_indexes" ], "description": "Create a new knowledge index.", "operationId": "create_index", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeIndexRequest" } } }, "required": true }, "responses": { "201": { "description": "Knowledge index created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeIndexResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Duplicate knowledge index name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-indexes/{index_id}": { "get": { "tags": [ "knowledge_indexes" ], "description": "Get a knowledge index by ID.", "operationId": "get_index", "parameters": [ { "name": "index_id", "in": "path", "description": "Knowledge index ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Knowledge index found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeIndexResponse" } } } }, "404": { "description": "Knowledge index not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "knowledge_indexes" ], "description": "Delete a knowledge index.", "operationId": "delete_index", "parameters": [ { "name": "index_id", "in": "path", "description": "Knowledge index ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Knowledge index archived" }, "404": { "description": "Knowledge index not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "knowledge_indexes" ], "description": "Update a knowledge index. Only provided fields are modified.", "operationId": "update_index", "parameters": [ { "name": "index_id", "in": "path", "description": "Knowledge index ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeIndexRequest" } } }, "required": true }, "responses": { "200": { "description": "Knowledge index updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeIndexResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Knowledge index not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Duplicate knowledge index name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-indexes/{index_id}/documents": { "get": { "tags": [ "knowledge_indexes" ], "description": "List documents inside a knowledge index.", "operationId": "list_documents", "parameters": [ { "name": "index_id", "in": "path", "description": "Knowledge index ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_KnowledgeIndexDocumentResponse" } } } }, "404": { "description": "Knowledge index not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/knowledge-indexes/{index_id}/sync": { "post": { "tags": [ "knowledge_indexes" ], "description": "Enqueue a manual sync of a knowledge index.", "operationId": "sync_index", "parameters": [ { "name": "index_id", "in": "path", "description": "Knowledge index ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeIndexResponse" } } } }, "400": { "description": "Knowledge index is archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Knowledge index not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/mcp-servers": { "get": { "tags": [ "mcp-servers" ], "summary": "GET /v1/mcp-servers - List all MCP servers", "operationId": "list_mcp_servers", "parameters": [ { "name": "search", "in": "query", "description": "Search by name or description (case-insensitive substring match).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "description": "Include archived MCP servers. Deleted MCP servers never appear in lists.", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "List of MCP servers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WithUrls_McpServer" } } } }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "mcp-servers" ], "summary": "POST /v1/mcp-servers - Create a new MCP server", "operationId": "create_mcp_server", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMcpServerRequest" } } }, "required": true }, "responses": { "201": { "description": "MCP server created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_McpServer" } } } }, "400": { "description": "Invalid input or duplicate name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/mcp-servers/catalog": { "get": { "tags": [ "mcp-servers" ], "description": "List a cursor-paginated MCP server catalog with active-agent usage counts for the selected organization.", "operationId": "list_mcp_server_catalog", "parameters": [ { "name": "cursor", "in": "query", "description": "Continue after this MCP server ID.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Page size (default: 50, max: 100).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Cursor-paginated MCP server catalog with active-agent usage counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCatalogResponse" } } } }, "400": { "description": "Invalid cursor or limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/mcp-servers/config": { "get": { "tags": [ "mcp-servers" ], "summary": "GET /v1/mcp-servers/config", "description": "Returns which MCP server policies the caller satisfies.", "operationId": "mcp_server_config", "responses": { "200": { "description": "Resource config for MCP servers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceConfigResponse" } } } } } } }, "/v1/mcp-servers/{server_id}": { "get": { "tags": [ "mcp-servers" ], "summary": "GET /v1/mcp-servers/{server_id} - Get MCP server by ID", "operationId": "get_mcp_server", "parameters": [ { "name": "server_id", "in": "path", "description": "MCP server ID (prefixed, e.g., mcp_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP server found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_McpServer" } } } }, "400": { "description": "Invalid server ID" }, "404": { "description": "MCP server not found" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "mcp-servers" ], "summary": "DELETE /v1/mcp-servers/{server_id} - Delete MCP server", "operationId": "delete_mcp_server", "parameters": [ { "name": "server_id", "in": "path", "description": "MCP server ID (prefixed, e.g., mcp_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "MCP server deleted successfully" }, "400": { "description": "Invalid server ID" }, "404": { "description": "MCP server not found" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "mcp-servers" ], "summary": "PATCH /v1/mcp-servers/{server_id} - Update MCP server", "operationId": "update_mcp_server", "parameters": [ { "name": "server_id", "in": "path", "description": "MCP server ID (prefixed, e.g., mcp_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMcpServerRequest" } } }, "required": true }, "responses": { "200": { "description": "MCP server updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_McpServer" } } } }, "400": { "description": "Invalid server ID or input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "MCP server not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/mcp-servers/{server_id}/usage": { "get": { "tags": [ "mcp-servers" ], "description": "Get the bounded active-agent impact summary used before archiving an MCP server preset.", "operationId": "get_mcp_server_usage", "parameters": [ { "name": "server_id", "in": "path", "description": "MCP server ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bounded active-agent archive impact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerUsageResponse" } } } }, "400": { "description": "Invalid MCP server ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "MCP server not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/me/invitations": { "get": { "tags": [ "organization invitations" ], "description": "List actionable organization invitations addressed to the authenticated user's verified email.", "operationId": "list_my_invitations", "responses": { "200": { "description": "Actionable invitations for the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_MyInvitationResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Email address is not verified" }, "500": { "description": "Internal server error" } } } }, "/v1/me/invitations/{public_id}/accept": { "post": { "tags": [ "organization invitations" ], "description": "Accept an actionable organization invitation addressed to the authenticated user's verified email.", "operationId": "accept_my_invitation", "parameters": [ { "name": "public_id", "in": "path", "description": "Public invitation ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInviteResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Email is unverified" }, "404": { "description": "Invitation not found" }, "409": { "description": "Invitation is revoked, accepted, or no longer actionable" }, "410": { "description": "Invitation expired" } } } }, "/v1/memories": { "get": { "tags": [ "memory" ], "description": "List workspace memories.", "operationId": "list_memories", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "List memories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_Memory" } } } } } }, "post": { "tags": [ "memory" ], "description": "Create a new workspace memory.", "operationId": "create_memory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMemoryRequest" } } }, "required": true }, "responses": { "201": { "description": "Memory created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Memory" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Duplicate memory name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/memories/{memory_id}": { "get": { "tags": [ "memory" ], "description": "Get a workspace memory by ID.", "operationId": "get_memory", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Memory found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Memory" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "memory" ], "description": "Delete a workspace memory.", "operationId": "delete_memory", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Memory archived" }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "memory" ], "description": "Update a workspace memory. Only provided fields are modified.", "operationId": "update_memory", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryRequest" } } }, "required": true }, "responses": { "200": { "description": "Memory updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Memory" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Duplicate memory name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/memories/{memory_id}/fs": { "get": { "tags": [ "memory" ], "description": "List immediate children of the Memory root.", "operationId": "list_root", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Directory listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_MemoryFileInfo" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/memories/{memory_id}/fs/_/download/{path}": { "get": { "tags": [ "memory" ], "description": "Download raw bytes of a Memory file.", "operationId": "download_action", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "File path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw file bytes" }, "400": { "description": "Path is a directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/memories/{memory_id}/fs/_/grep": { "post": { "tags": [ "memory" ], "description": "Search Memory files by regex.", "operationId": "grep_action", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrepRequest" } } }, "required": true }, "responses": { "200": { "description": "Matched files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_MemoryGrepResult" } } } }, "400": { "description": "Invalid pattern", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/memories/{memory_id}/fs/_/stat": { "post": { "tags": [ "memory" ], "description": "Stat a file or directory inside a Memory.", "operationId": "stat_action", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatRequest" } } }, "required": true }, "responses": { "200": { "description": "File metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryFileInfo" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/memories/{memory_id}/fs/{path}": { "get": { "tags": [ "memory" ], "description": "Read a file or list a directory inside a Memory.", "operationId": "get_file", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "File or directory path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File content or directory listing" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "memory" ], "description": "Update a file's content. Directories cannot be updated.", "operationId": "update_file", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Target path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryFileRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryFile" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Source-backed Memory is read-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "memory" ], "description": "Create a file or directory inside a Memory.", "operationId": "create_file", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Target path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMemoryFileRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryFileInfo" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Source-backed Memory is read-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Path already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "memory" ], "description": "Delete a file or directory. Pass `recursive=true` to delete non-empty directories.", "operationId": "delete_file", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Target path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Source-backed Memory is read-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Directory not empty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/memories/{memory_id}/sync": { "post": { "tags": [ "memory" ], "description": "Trigger a synchronous sync of a memory now.", "operationId": "sync_memory_now", "parameters": [ { "name": "memory_id", "in": "path", "description": "Memory ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Memory sync queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Memory" } } } }, "400": { "description": "Invalid sync request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Memory not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/models": { "get": { "tags": [ "models" ], "summary": "List all models across all providers", "operationId": "list_all_models", "parameters": [ { "name": "source", "in": "query", "description": "Filter by model source (manual, discovered, predefined)", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelSource" } ] } }, { "name": "include_stale", "in": "query", "description": "Include models that are stale (not seen in recent sync). Default: true", "required": false, "schema": { "type": "boolean" } }, { "name": "favorites_only", "in": "query", "description": "Only return favorite models. Default: false", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of all models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WithUrls_ModelWithProvider" } } } } } } }, "/v1/models/config": { "get": { "tags": [ "models" ], "summary": "GET /v1/models/config", "operationId": "model_config", "responses": { "200": { "description": "Resource config for LLM models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceConfigResponse" } } } } } } }, "/v1/models/{id}": { "get": { "tags": [ "models" ], "summary": "Get a specific model with provider info and profile", "operationId": "get_model", "parameters": [ { "name": "id", "in": "path", "description": "Model ID (prefixed, e.g., mod_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_ModelWithProvider" } } } }, "400": { "description": "Invalid model ID" }, "404": { "description": "Model not found" } } }, "delete": { "tags": [ "models" ], "summary": "Delete a model", "operationId": "delete_model", "parameters": [ { "name": "id", "in": "path", "description": "Model ID (prefixed, e.g., mod_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Model deleted" }, "400": { "description": "Invalid model ID" }, "404": { "description": "Model not found" } } }, "patch": { "tags": [ "models" ], "summary": "Update a model", "operationId": "update_model", "parameters": [ { "name": "id", "in": "path", "description": "Model ID (prefixed, e.g., mod_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateModelRequest" } } }, "required": true }, "responses": { "200": { "description": "Model updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Model" } } } }, "400": { "description": "Invalid model ID" }, "404": { "description": "Model not found" } } } }, "/v1/orgs": { "get": { "tags": [ "Organizations" ], "summary": "GET /v1/orgs - List organizations the current user belongs to", "operationId": "list_organizations", "responses": { "200": { "description": "List of organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_OrganizationResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "tags": [ "Organizations" ], "summary": "POST /v1/orgs - Create a new organization", "operationId": "create_organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" } } }, "required": true }, "responses": { "201": { "description": "Organization created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/orgs/{org}": { "get": { "tags": [ "Organizations" ], "summary": "GET /v1/orgs/:org - Get organization details", "operationId": "get_organization", "parameters": [ { "name": "org", "in": "path", "description": "Organization public ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "tags": [ "Organizations" ], "summary": "PATCH /v1/orgs/:org - Update organization", "operationId": "update_organization", "parameters": [ { "name": "org", "in": "path", "description": "Organization public ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/orgs/{org}/feature-flags": { "get": { "tags": [ "Organizations" ], "summary": "GET /v1/orgs/{org}/feature-flags — effective flags for the organization.", "operationId": "get_org_feature_flags", "parameters": [ { "name": "org", "in": "path", "description": "Organization public id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Effective feature flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureFlagMap" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "tags": [ "Organizations" ], "summary": "PATCH /v1/orgs/{org}/feature-flags — update org opt-in (admin only).", "operationId": "update_org_feature_flags", "parameters": [ { "name": "org", "in": "path", "description": "Organization public id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgFeatureFlagsRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated effective flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureFlagMap" } } } }, "400": { "description": "Invalid flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/orgs/{org}/feature-flags/platform": { "get": { "tags": [ "Organizations" ], "summary": "GET /v1/orgs/{org}/feature-flags/platform — every flag, including the\nplatform-managed ones, for the operator console.", "description": "Platform users only. The tenant-facing settings route deliberately omits\nthese rows, so this is where an operator sees what a tenant is enrolled in.", "operationId": "get_platform_feature_flag_settings", "parameters": [ { "name": "org", "in": "path", "description": "Organization public id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Feature flag settings, platform view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgFeatureFlagsSettingsResponse" } } } }, "403": { "description": "Platform user access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "tags": [ "Organizations" ], "summary": "PATCH /v1/orgs/{org}/feature-flags/platform — enrol an organization in a\nplatform-managed feature.", "description": "Platform users only, and limited to platform-managed flags: an operator\nsetting a tenant's own preferences would be acting as the tenant, which this\nsurface does not do. Omitted flags are unchanged, so enrolling one org in one\nfeature cannot disturb another setting.", "operationId": "update_platform_feature_flags", "parameters": [ { "name": "org", "in": "path", "description": "Organization public id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgFeatureFlagsRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated effective flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureFlagMap" } } } }, "400": { "description": "Not a platform-managed flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Platform user access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/orgs/{org}/feature-flags/settings": { "get": { "tags": [ "Organizations" ], "summary": "GET /v1/orgs/{org}/feature-flags/settings — catalog with system/org/effective state.", "operationId": "get_org_feature_flag_settings", "parameters": [ { "name": "org", "in": "path", "description": "Organization public id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Feature flag settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgFeatureFlagsSettingsResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/orgs/{org}/onboarding/complete": { "post": { "tags": [ "Organizations" ], "summary": "POST /v1/orgs/:org/onboarding/complete - Mark the org's onboarding wizard as\nfinished (or skipped). Idempotent: the timestamp is set only when NULL.", "description": "Authz mirrors the org-scoped mutations above (admin+), but resolves\nmembership/role from the DB rather than the auth token — a brand-new org may\nnot yet appear in the caller's token, and onboarding completion is exactly\nthat just-created case.", "operationId": "complete_org_onboarding", "parameters": [ { "name": "org", "in": "path", "description": "Organization public ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Onboarding marked complete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "403": { "description": "Not an admin of the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/payments/accounts": { "get": { "tags": [ "payments" ], "description": "List payment accounts.", "operationId": "list_payment_accounts", "parameters": [ { "name": "owner_type", "in": "query", "description": "Filter to a single owner class (user, agent identity, or organization).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "owner_id", "in": "query", "description": "Filter to a specific owner principal id.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "List payment accounts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAccount" } } } } } } }, "post": { "tags": [ "payments" ], "description": "Create a new payment account.", "operationId": "create_payment_account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentAccountRequest" } } }, "required": true }, "responses": { "201": { "description": "Payment account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAccount" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payments/accounts/{payment_account_id}": { "get": { "tags": [ "payments" ], "description": "Get a payment account by ID.", "operationId": "get_payment_account", "parameters": [ { "name": "payment_account_id", "in": "path", "description": "Payment account ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAccount" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "payments" ], "description": "Disable a payment account without deleting it.", "operationId": "disable_payment_account", "parameters": [ { "name": "payment_account_id", "in": "path", "description": "Payment account ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Payment account disabled" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "payments" ], "description": "Update a payment account. Only provided fields are modified.", "operationId": "update_payment_account", "parameters": [ { "name": "payment_account_id", "in": "path", "description": "Payment account ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentAccountRequest" } } }, "required": true }, "responses": { "200": { "description": "Payment account updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAccount" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payments/attempts": { "get": { "tags": [ "payments" ], "description": "List recent payment attempts (operator audit view).", "operationId": "list_payment_attempts", "parameters": [ { "name": "session_id", "in": "query", "description": "Filter to attempts originating from a specific session.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of attempts returned. Defaults to 50.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "List payment attempts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAttempt" } } } } } } } }, "/v1/payments/policies": { "get": { "tags": [ "payments" ], "description": "List payment policies.", "operationId": "list_payment_policies", "parameters": [ { "name": "payment_account_id", "in": "query", "description": "Filter to policies that authorize a specific payment account.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "subject_type", "in": "query", "description": "Filter to a single subject class.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "subject_id", "in": "query", "description": "Filter to a specific subject principal id.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "List payment policies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentPolicy" } } } } } } }, "post": { "tags": [ "payments" ], "description": "Create a new payment policy.", "operationId": "create_payment_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentPolicyRequest" } } }, "required": true }, "responses": { "201": { "description": "Payment policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPolicy" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payments/policies/{payment_policy_id}": { "get": { "tags": [ "payments" ], "description": "Get a payment policy by ID.", "operationId": "get_payment_policy", "parameters": [ { "name": "payment_policy_id", "in": "path", "description": "Payment policy ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPolicy" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "payments" ], "description": "Disable a payment policy without deleting it.", "operationId": "disable_payment_policy", "parameters": [ { "name": "payment_policy_id", "in": "path", "description": "Payment policy ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Payment policy disabled" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "payments" ], "description": "Update a payment policy. Only provided fields are modified.", "operationId": "update_payment_policy", "parameters": [ { "name": "payment_policy_id", "in": "path", "description": "Payment policy ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Payment policy updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPolicy" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/plugin_marketplaces": { "get": { "tags": [ "plugins" ], "summary": "GET /v1/plugin_marketplaces", "operationId": "list_plugin_marketplaces", "parameters": [ { "name": "search", "in": "query", "description": "Search by name (case-insensitive substring match).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "List of plugin marketplaces" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "plugins" ], "summary": "POST /v1/plugin_marketplaces", "operationId": "create_plugin_marketplace", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePluginMarketplaceRequest" } } }, "required": true }, "responses": { "201": { "description": "Marketplace created" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/plugin_marketplaces/{id}": { "get": { "tags": [ "plugins" ], "summary": "GET /v1/plugin_marketplaces/{id}", "operationId": "get_plugin_marketplace", "parameters": [ { "name": "id", "in": "path", "description": "Marketplace ID (plgmkt_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Marketplace found" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "plugins" ], "summary": "DELETE /v1/plugin_marketplaces/{id}", "operationId": "delete_plugin_marketplace", "parameters": [ { "name": "id", "in": "path", "description": "Marketplace ID (plgmkt_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Marketplace deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "plugins" ], "summary": "PATCH /v1/plugin_marketplaces/{id}", "operationId": "update_plugin_marketplace", "parameters": [ { "name": "id", "in": "path", "description": "Marketplace ID (plgmkt_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePluginMarketplaceRequest" } } }, "required": true }, "responses": { "200": { "description": "Marketplace updated" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/plugin_marketplaces/{id}/plugins": { "get": { "tags": [ "plugins" ], "summary": "GET /v1/plugin_marketplaces/{id}/plugins", "operationId": "get_marketplace_catalog", "parameters": [ { "name": "id", "in": "path", "description": "Marketplace ID (plgmkt_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Catalog entries" }, "400": { "description": "Marketplace not yet synced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/plugin_marketplaces/{id}/sync": { "post": { "tags": [ "plugins" ], "summary": "POST /v1/plugin_marketplaces/{id}/sync", "operationId": "sync_plugin_marketplace", "parameters": [ { "name": "id", "in": "path", "description": "Marketplace ID (plgmkt_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Marketplace synced" }, "400": { "description": "Sync not supported or source error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/plugins": { "get": { "tags": [ "plugins" ], "summary": "GET /v1/plugins", "operationId": "list_plugins", "parameters": [ { "name": "search", "in": "query", "description": "Search by name (case-insensitive substring match).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "List of installed plugins" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "plugins" ], "summary": "POST /v1/plugins", "operationId": "install_plugin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallPluginRequest" } } }, "required": true }, "responses": { "201": { "description": "Plugin installed" }, "400": { "description": "Compilation or source error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Plugin already installed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/plugins/{id}": { "get": { "tags": [ "plugins" ], "summary": "GET /v1/plugins/{id}", "operationId": "get_plugin", "parameters": [ { "name": "id", "in": "path", "description": "Plugin install ID (plugin_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Installed plugin" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "plugins" ], "summary": "DELETE /v1/plugins/{id}", "operationId": "uninstall_plugin", "parameters": [ { "name": "id", "in": "path", "description": "Plugin install ID (plugin_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Plugin uninstalled" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "plugins" ], "summary": "PATCH /v1/plugins/{id}", "operationId": "patch_installed_plugin", "parameters": [ { "name": "id", "in": "path", "description": "Plugin install ID (plugin_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInstalledPluginRequest" } } }, "required": true }, "responses": { "200": { "description": "Plugin updated" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/plugins/{id}/update": { "post": { "tags": [ "plugins" ], "summary": "POST /v1/plugins/{id}/update", "operationId": "update_plugin", "parameters": [ { "name": "id", "in": "path", "description": "Plugin install ID (plugin_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plugin updated" }, "400": { "description": "No marketplace or source error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/providers": { "get": { "tags": [ "providers" ], "summary": "List all LLM providers", "operationId": "list_providers", "responses": { "200": { "description": "List of providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WithUrls_Provider" } } } } } }, "post": { "tags": [ "providers" ], "summary": "Create a new LLM provider", "operationId": "create_provider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Provider created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Provider" } } } }, "400": { "description": "Invalid request" }, "500": { "description": "Internal error" } } } }, "/v1/providers/check-credentials": { "post": { "tags": [ "providers" ], "summary": "Check whether a provider accepts an API key, without storing it", "description": "Used by org setup so a key the provider will reject is caught at entry\ninstead of at the first agent run. Nothing is persisted.", "operationId": "check_credentials", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCredentialsRequest" } } }, "required": true }, "responses": { "200": { "description": "Check completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialCheckResult" } } } }, "400": { "description": "Invalid request" }, "500": { "description": "Internal error" } } } }, "/v1/providers/config": { "get": { "tags": [ "providers" ], "summary": "GET /v1/providers/config", "operationId": "provider_config", "responses": { "200": { "description": "Resource config for providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvidersConfigResponse" } } } } } } }, "/v1/providers/{id}": { "get": { "tags": [ "providers" ], "summary": "Get a specific LLM provider", "operationId": "get_provider", "parameters": [ { "name": "id", "in": "path", "description": "Provider ID (prefixed, e.g., prov_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Provider found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Provider" } } } }, "400": { "description": "Invalid provider ID" }, "404": { "description": "Provider not found" } } }, "delete": { "tags": [ "providers" ], "summary": "Delete an LLM provider", "operationId": "delete_provider", "parameters": [ { "name": "id", "in": "path", "description": "Provider ID (prefixed, e.g., prov_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Provider deleted" }, "400": { "description": "Invalid provider ID" }, "404": { "description": "Provider not found" } } }, "patch": { "tags": [ "providers" ], "summary": "Update an LLM provider", "operationId": "update_provider", "parameters": [ { "name": "id", "in": "path", "description": "Provider ID (prefixed, e.g., prov_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "Provider updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Provider" } } } }, "400": { "description": "Invalid provider ID" }, "404": { "description": "Provider not found" } } } }, "/v1/providers/{id}/sync-models": { "post": { "tags": [ "providers" ], "summary": "Sync models from an LLM provider", "description": "Fetches the list of available models from the provider's API and updates\nthe database. Only works for providers with standard base URLs (not custom).", "operationId": "sync_models", "parameters": [ { "name": "id", "in": "path", "description": "Provider ID (prefixed, e.g., prov_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Models synced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncModelsResponse" } } } }, "400": { "description": "Invalid provider ID" }, "404": { "description": "Provider not found" }, "500": { "description": "Sync failed" } } } }, "/v1/providers/{provider_id}/models": { "get": { "tags": [ "models" ], "summary": "List models for a specific provider", "operationId": "list_provider_models", "parameters": [ { "name": "provider_id", "in": "path", "description": "Provider ID (prefixed, e.g., prov_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WithUrls_Model" } } } }, "400": { "description": "Invalid provider ID" } } }, "post": { "tags": [ "models" ], "summary": "Create a new model for a provider", "operationId": "create_model", "parameters": [ { "name": "provider_id", "in": "path", "description": "Provider ID (prefixed, e.g., prov_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModelRequest" } } }, "required": true }, "responses": { "201": { "description": "Model created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Model" } } } }, "400": { "description": "Invalid provider ID" }, "404": { "description": "Provider not found" }, "500": { "description": "Internal error" } } } }, "/v1/reports/admin/backfill": { "post": { "tags": [ "reporting" ], "description": "Run a reporting projector to refresh derived data (operator action).", "operationId": "backfill_reporting", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingBackfillRequest" } } }, "required": true }, "responses": { "200": { "description": "Reporting backfill enqueue result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingBackfillResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/admin/diagnostics": { "get": { "tags": [ "reporting" ], "description": "Return diagnostics for the reporting subsystem (operator view).", "operationId": "get_diagnostics", "responses": { "200": { "description": "Reporting diagnostics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingDiagnostics" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/catalog": { "get": { "tags": [ "reporting" ], "description": "Return the available reporting datasets and their schemas.", "operationId": "get_catalog", "responses": { "200": { "description": "Reporting semantic catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetCatalog" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/projector/run": { "post": { "tags": [ "reporting" ], "description": "Run a reporting projector to refresh derived data (operator action).", "operationId": "run_projector", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items returned in this page.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Reporting projector run result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectorRunResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/query": { "post": { "tags": [ "reporting" ], "description": "Run an ad-hoc reporting query against a registered dataset.", "operationId": "run_query", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportQuery" } } }, "required": true }, "responses": { "200": { "description": "Reporting query result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResult" } } } }, "400": { "description": "Invalid semantic query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/query/export": { "post": { "tags": [ "reporting" ], "description": "Run an ad-hoc reporting query and stream the result as CSV.", "operationId": "export_query", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportReportQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Exported report content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportExport" } } } }, "400": { "description": "Invalid semantic query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/saved": { "get": { "tags": [ "reporting" ], "description": "List saved reports.", "operationId": "list_saved_reports", "responses": { "200": { "description": "Saved reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_SavedReport" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "reporting" ], "description": "Create a new saved report.", "operationId": "create_saved_report", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSavedReportRequest" } } }, "required": true }, "responses": { "201": { "description": "Saved report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedReport" } } } }, "400": { "description": "Invalid saved report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/saved/{report_id}": { "get": { "tags": [ "reporting" ], "description": "Get a saved report by ID.", "operationId": "get_saved_report", "parameters": [ { "name": "report_id", "in": "path", "description": "Saved report ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedReport" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Saved report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "reporting" ], "description": "Delete a saved report.", "operationId": "delete_saved_report", "parameters": [ { "name": "report_id", "in": "path", "description": "Saved report ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Saved report deleted" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Saved report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "reporting" ], "description": "Update a saved report. Only provided fields are modified.", "operationId": "update_saved_report", "parameters": [ { "name": "report_id", "in": "path", "description": "Saved report ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSavedReportRequest" } } }, "required": true }, "responses": { "200": { "description": "Saved report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedReport" } } } }, "400": { "description": "Invalid saved report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Saved report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/saved/{report_id}/export": { "post": { "tags": [ "reporting" ], "description": "Run a previously saved reporting query and stream the result as CSV.", "operationId": "export_saved_report", "parameters": [ { "name": "report_id", "in": "path", "description": "Saved report ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSavedReportRequest" } } }, "required": true }, "responses": { "200": { "description": "Exported report content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportExport" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Saved report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/saved/{report_id}/run": { "post": { "tags": [ "reporting" ], "description": "Run a previously saved reporting query and return the result.", "operationId": "run_saved_report", "parameters": [ { "name": "report_id", "in": "path", "description": "Saved report ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reporting query result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResult" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Saved report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/resolve-org": { "get": { "tags": [ "users" ], "summary": "GET /v1/resolve-org — resolve the owning org for a resource id.", "description": "Returns the owning organization only when it is one the authenticated\ncaller already belongs to. For every other case (unknown id, unknown\nprefix, resource belongs to a non-member org) the endpoint returns 404 —\nthis preserves the org-enumeration guarantee: callers cannot use this\nendpoint to probe for the existence of resources outside their own orgs.", "operationId": "resolve_org", "parameters": [ { "name": "id", "in": "query", "description": "Prefixed public ID of the resource", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owning org resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveOrgResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Unknown id, unknown prefix, or caller is not a member of the owning org" } } } }, "/v1/sessions": { "get": { "tags": [ "sessions" ], "summary": "GET /v1/sessions - List sessions in organization", "operationId": "list_sessions", "parameters": [ { "name": "agent_id", "in": "query", "description": "Filter sessions by agent ID.", "required": false, "schema": { "type": [ "string", "null" ] }, "example": "agent_01933b5a00007000800000000000001" }, { "name": "search", "in": "query", "description": "Search by title (case-insensitive substring match).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "source", "in": "query", "description": "Comma-separated session sources: `chat`, `api`, `slack`, `ag_ui`,\n`fcp`, `schedule`, `webhook`, `a2a`, `eval`, `subagent`, `unknown`.", "required": false, "schema": { "type": [ "string", "null" ] }, "example": "chat" }, { "name": "status", "in": "query", "description": "Comma-separated derived statuses: `running`, `paused`, `failed`,\n`completed`, `idle`.", "required": false, "schema": { "type": [ "string", "null" ] }, "example": "running,failed" }, { "name": "mine", "in": "query", "description": "Restrict to sessions owned by the calling user.", "required": false, "schema": { "type": [ "boolean", "null" ] }, "example": true }, { "name": "include_archived", "in": "query", "description": "Include archived sessions. Defaults to false.", "required": false, "schema": { "type": [ "boolean", "null" ] }, "example": true }, { "name": "created_after", "in": "query", "description": "Inclusive lower bound on creation time (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] }, "example": "2026-08-01T00:00:00Z" }, { "name": "created_before", "in": "query", "description": "Exclusive upper bound on creation time (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ] }, "example": "2026-08-09T00:00:00Z" }, { "name": "order", "in": "query", "description": "`created_at` (default) or `last_activity`.", "required": false, "schema": { "type": [ "string", "null" ] }, "example": "last_activity" }, { "name": "offset", "in": "query", "description": "Number of items to skip (for pagination).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "default": 0, "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Maximum number of items to return (for pagination).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_WithUrls_Session" } } } }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "sessions" ], "summary": "POST /v1/sessions - Create a new session", "operationId": "create_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" }, "example": { "harness_name": "generic", "tags": [ "debugging", "urgent" ], "title": "Debug login issue" } } }, "required": true }, "responses": { "201": { "description": "Session created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Session" }, "example": { "created_at": "2026-05-27T15:24:00Z", "harness_id": "harness_01933b5a00007000800000000000001", "id": "session_01933b5a00007000800000000000001", "organization_id": "org_00000000000000000000000000000001", "owner_principal_id": "principal_01933b5a000070008000000000000001", "self_url": "https://app.everruns.com/api/v1/sessions/session_01933b5a00007000800000000000001", "status": "started", "tags": [ "debugging", "urgent" ], "title": "Debug login issue", "ui_link": "https://app.everruns.com/sessions/session_01933b5a00007000800000000000001/chat", "updated_at": "2026-05-27T15:24:00Z", "view_url": "https://app.everruns.com/sessions/session_01933b5a00007000800000000000001/chat" } } } }, "404": { "description": "Harness, Agent, or Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "harness_not_found", "detail": "Harness 'generic' not found in org org_00000000000000000000000000000001.", "status": 404, "title": "Not Found", "type": "https://docs.everruns.com/errors/harness_not_found" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/facets": { "get": { "tags": [ "sessions" ], "summary": "GET /v1/sessions/facets - Facet counts and masthead metrics", "operationId": "get_session_facets", "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "agent_01933b5a00007000800000000000001" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "mine", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Facet counts over the applied filters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFacetsResponse" } } } }, "400": { "description": "Unknown filter value" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/stats": { "get": { "tags": [ "sessions" ], "summary": "GET /v1/sessions/stats - Get session counts by status", "operationId": "get_session_stats", "responses": { "200": { "description": "Session statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatsResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}": { "get": { "tags": [ "sessions" ], "summary": "GET /v1/sessions/{session_id} - Get session", "operationId": "get_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Session" } } } }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "sessions" ], "summary": "DELETE /v1/sessions/{session_id} - Delete session", "operationId": "delete_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session deleted successfully" }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } }, "x-side-effect": "reversible" }, "patch": { "tags": [ "sessions" ], "summary": "PATCH /v1/sessions/{session_id} - Update session", "operationId": "update_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Session updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Session" } } } }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/archive": { "put": { "tags": [ "sessions" ], "summary": "PUT /v1/sessions/{session_id}/archive - Archive session", "operationId": "archive_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session archived successfully" }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "sessions" ], "summary": "DELETE /v1/sessions/{session_id}/archive - Restore an archived session", "operationId": "unarchive_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session unarchived successfully" }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/cancel": { "post": { "tags": [ "sessions" ], "summary": "POST /v1/sessions/{session_id}/cancel - Cancel current turn", "description": "Cancels the currently running turn in the session. If no turn is running,\nthis is a no-op and returns success (idempotent). When a turn is active:\n1. Cancel the underlying workflow execution\n2. Emit a turn.cancelled event\n3. Insert an agent message indicating the turn was cancelled\n4. Set the session status back to idle", "operationId": "cancel_turn", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Turn cancelled, or no-op (status: no_op) if no turn was running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelTurnResponse" }, "example": { "message": "Turn cancelled successfully", "status": "cancelled" } } } }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_00000000000000000000000000000001.", "status": 404, "title": "Not Found", "type": "https://docs.everruns.com/errors/session_not_found" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/context-report": { "get": { "tags": [ "sessions" ], "summary": "GET /v1/sessions/{session_id}/context-report - Latest context breakdown", "operationId": "get_session_context_report", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session context report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionContextReport" } } } }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/databases": { "get": { "tags": [ "session-databases" ], "summary": "GET /v1/sessions/{session_id}/databases", "operationId": "list_databases", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of databases", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_DatabaseInfoResponse" } } } }, "400": { "description": "Invalid session ID" } } }, "post": { "tags": [ "session-databases" ], "summary": "POST /v1/sessions/{session_id}/databases", "operationId": "create_database", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatabaseRequest" } } }, "required": true }, "responses": { "201": { "description": "Database created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseInfoResponse" } } } }, "400": { "description": "Invalid name or session ID" }, "409": { "description": "Database already exists" }, "422": { "description": "Session database limit exceeded" } } } }, "/v1/sessions/{session_id}/databases/{name}": { "get": { "tags": [ "session-databases" ], "summary": "GET /v1/sessions/{session_id}/databases/{name}", "operationId": "get_database", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Database name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Database info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseInfoResponse" } } } }, "404": { "description": "Database not found" } } }, "delete": { "tags": [ "session-databases" ], "summary": "DELETE /v1/sessions/{session_id}/databases/{name}", "operationId": "delete_database", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Database name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Database deleted" }, "404": { "description": "Database not found" } } } }, "/v1/sessions/{session_id}/databases/{name}/schema": { "get": { "tags": [ "session-databases" ], "summary": "GET /v1/sessions/{session_id}/databases/{name}/schema", "operationId": "get_schema", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Database name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Database schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "404": { "description": "Database not found" } } } }, "/v1/sessions/{session_id}/environment": { "get": { "tags": [ "environments" ], "description": "Get the environment a session runs in: target, containment, and what it can actually do.", "operationId": "get_session_environment", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolved session environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionEnvironmentResponse" }, "example": { "capabilities": { "native_processes": false, "network_enforced": true, "packages": false, "portable_checkpoint": true, "ports": false, "pty": false }, "containment": { "level": "isolated", "network": "deny" }, "durability": "checkpointed", "resolved_from": "capabilities", "source_capability": "bashkit_shell", "target": { "kind": "vfs", "provider": "bashkit" } } } } }, "404": { "description": "Session not found" } } } }, "/v1/sessions/{session_id}/events": { "get": { "tags": [ "events" ], "summary": "GET /v1/sessions/{session_id}/events - List events (JSON)", "description": "Returns events for a session as a JSON array. Supports filtering by event type\nvia `types` (positive: only these types) and `exclude` (negative: remove these types).\nWhen both are provided, `types` narrows first, then `exclude` removes from that set.\nBoth accept only known event types (max 25 per parameter). Unknown types return 400.\n\n## Pagination\n\nSupports backward pagination via `limit` and `before_sequence`:\n- `limit=200` returns the last 200 events (oldest→newest)\n- `limit=200&before_sequence=4500` returns 200 events before sequence 4500\n- When `limit` is provided, the response includes an `X-Total-Count` header\n with the count of non-delta events for the session\n- Turn boundary snapping: when fetching older pages, the batch boundary\n snaps to the nearest `turn.started` event to avoid splitting turns\n- Without `limit`, all events are returned (backward compatible)", "operationId": "list_events", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., sess_...)", "required": true, "schema": { "type": "string" } }, { "name": "since_id", "in": "query", "description": "Filter events with ID greater than this event ID (prefixed format: event_{32-hex})", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/eventId" } ] } }, { "name": "types", "in": "query", "description": "Positive type filter (repeat key). Empty = all types.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "exclude", "in": "query", "description": "Event types to exclude (repeat key); applied after `types`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "limit", "in": "query", "description": "Max events to return (backward pagination). When set, returns the last N events\n(or last N before `before_sequence`). Results are ordered oldest→newest.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "maximum": 1000, "minimum": 1 } }, { "name": "before_sequence", "in": "query", "description": "Cursor for backward pagination: only return events with sequence < this value.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } }, { "name": "after_sequence", "in": "query", "description": "Forward cursor: only return events with sequence > this value.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } }, { "name": "around", "in": "query", "description": "Anchor event id: returns up to `window` events on each side (default 50, max 500).\nMutually exclusive with `since_id`, `after_sequence`, and `before_sequence` — 400 if combined.", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/eventId" } ] } }, { "name": "window", "in": "query", "description": "Window size for `around` (events on each side). Defaults to 50, max 500.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } }, { "name": "from_ts", "in": "query", "description": "Lower bound on `created_at` (RFC 3339, e.g. `2025-05-07T00:00:00Z`).", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to_ts", "in": "query", "description": "Upper bound on `created_at`.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "turn_id", "in": "query", "description": "Filter by `context.turn_id` (prefixed id, e.g. `turn_...`).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "exec_id", "in": "query", "description": "Filter by `context.exec_id` (prefixed id, e.g. `exec_...`).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "trace_id", "in": "query", "description": "Filter by `context.trace_id`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "tags", "in": "query", "description": "Tag any-match against `events.tags` (repeat key for multiple values).", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "tool_name", "in": "query", "description": "Filter by `data.tool_name` — useful for narrowing `tool.*` events.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "q", "in": "query", "description": "Full-text search (Postgres tsvector; substring fallback for in-memory mode).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "order_desc", "in": "query", "description": "When true, return newest first; default oldest first.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Events list", "headers": { "X-Total-Count": { "schema": { "type": "integer", "format": "int64" }, "description": "Total non-delta event count for the session (only present when limit is used)" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_Event" } } } }, "400": { "description": "Invalid session ID or invalid event type filter" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/events/summary": { "get": { "tags": [ "events" ], "summary": "GET /v1/sessions/{session_id}/events/summary - one-shot debug summary", "operationId": "events_summary", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., sess_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-type counts and time span for the session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsSummaryResult" } } } }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/export": { "get": { "tags": [ "sessions" ], "summary": "Export session messages as a JSONL file (default) or as an ATIF trajectory", "description": "Default (`format=jsonl`): all materialized messages (user, agent) as\nnewline-delimited JSON, one complete JSON object per line; delta events are\nexcluded. `format=atif` returns a single ATIF-v1.7 trajectory JSON document\nfolded from the session's event log (see `knowledge/evaluation/atif-adoption.md`); image\ncontent parts are exported as ATIF multimodal ContentParts. When an image\ncannot be materialized (an inline image with neither a URL nor bytes) it is\nflattened to an `\"[image]\"` marker and the response carries an\n`X-Atif-Images-Omitted` header with that count (usually 0 and absent).\nDocuments over the 50 MiB `ATIF_EXPORT_MAX_BYTES` cap are rejected with 413.\nThe response includes `Content-Disposition: attachment` for browser\ndownload.", "operationId": "export_session_jsonl", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Output format: jsonl (default) or atif", "required": false, "schema": { "type": "string" } }, { "name": "segmented", "in": "query", "description": "ATIF only: return byte-bounded segments linked by continued_trajectory_ref instead of one document", "required": false, "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "description": "ATIF segmented export: opaque continuation cursor from the previous segment", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSONL file with one message per line, or one ATIF trajectory JSON document (images export as multimodal ContentParts; X-Atif-Images-Omitted header only when an image could not be materialized). With segmented=true, one ATIF segment linked forward by continued_trajectory_ref.", "content": { "application/x-ndjson": {} } }, "400": { "description": "Invalid ID format, or malformed/foreign segmented-export cursor" }, "403": { "description": "Forbidden" }, "404": { "description": "Session not found" }, "413": { "description": "ATIF document exceeds the 50 MiB export cap; retry with segmented=true for a recoverable chunked export", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/fork": { "post": { "tags": [ "sessions" ], "summary": "POST /v1/sessions/{session_id}/fork - Fork a session into an independent copy", "operationId": "fork_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session to fork", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkSessionRequest" }, "example": { "tags": [ "experiment" ], "title": "Branch: try the async rewrite" } } }, "required": true }, "responses": { "201": { "description": "Fork created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Session" } } } }, "404": { "description": "Parent session, agent, or harness not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Parent session is mid-turn and cannot be forked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/git/branches": { "post": { "tags": [ "Session Git" ], "summary": "POST /v1/sessions/{session_id}/git/branches", "operationId": "create_branch", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBranchRequest" } } }, "required": true }, "responses": { "201": { "description": "Branch created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Invalid request" } } } }, "/v1/sessions/{session_id}/git/branches/{name}": { "delete": { "tags": [ "Session Git" ], "summary": "DELETE /v1/sessions/{session_id}/git/branches/{name}", "operationId": "delete_branch", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Branch name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Branch deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "404": { "description": "Branch not found" } } } }, "/v1/sessions/{session_id}/git/commit": { "post": { "tags": [ "Session Git" ], "summary": "POST /v1/sessions/{session_id}/git/commit", "operationId": "commit", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitRequest" } } }, "required": true }, "responses": { "201": { "description": "Commit created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitResult" } } } }, "400": { "description": "Invalid request" }, "404": { "description": "Session not found" } } } }, "/v1/sessions/{session_id}/git/diff": { "get": { "tags": [ "Session Git" ], "summary": "GET /v1/sessions/{session_id}/git/diff", "operationId": "diff", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "oid", "in": "query", "description": "Commit OID to diff", "required": true, "schema": { "type": "string" } }, { "name": "base", "in": "query", "description": "Base commit OID (default: parent)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Diff result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitDiff" } } } }, "400": { "description": "Invalid commit OID" }, "404": { "description": "Commit not found" } } } }, "/v1/sessions/{session_id}/git/log": { "get": { "tags": [ "Session Git" ], "summary": "GET /v1/sessions/{session_id}/git/log", "operationId": "log", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "ref", "in": "query", "description": "Ref to start from (default: HEAD)", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max commits (default: 50)", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Commit log", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GitCommitInfo" } } } } }, "404": { "description": "Session or ref not found" } } } }, "/v1/sessions/{session_id}/git/refs": { "get": { "tags": [ "Session Git" ], "summary": "GET /v1/sessions/{session_id}/git/refs", "operationId": "list_refs", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of refs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GitRefInfo" } } } } } } } }, "/v1/sessions/{session_id}/mcp-elicitation-consent": { "post": { "tags": [ "sessions" ], "summary": "POST /v1/sessions/{session_id}/mcp-elicitation-consent", "description": "Records a user's decision about a URL an MCP server asked them to open, and\nresumes the paused turn.", "operationId": "submit_elicitation_consent", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElicitationConsentRequest" } } }, "required": true }, "responses": { "200": { "description": "Decision recorded and workflow resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElicitationConsentResponse" } } } }, "400": { "description": "Invalid session ID or request" }, "404": { "description": "Session or pending elicitation not found" }, "409": { "description": "Session is not waiting for tool results" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/messages": { "get": { "tags": [ "messages" ], "summary": "GET /v1/sessions/{session_id}/messages - List messages (PRIMARY data)", "operationId": "list_messages", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., sess_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_Message" } } } }, "400": { "description": "Invalid ID format" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "messages" ], "summary": "POST /v1/sessions/{session_id}/messages - Create message (user message triggers workflow)", "operationId": "create_message", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., sess_...)", "required": true, "schema": { "type": "string" } }, { "name": "wait", "in": "query", "description": "Wait for turn completion and return the turn result.", "required": false, "schema": { "type": "boolean" } }, { "name": "timeout_ms", "in": "query", "description": "Max wait budget in milliseconds (default 120000, capped at 600000).\nOnly used with `wait=true`. On expiry the endpoint returns `202`\nwith the messages produced so far.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageRequest" } } }, "required": true }, "responses": { "200": { "description": "Waited turn reached a terminal state (?wait=true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageResult" } } } }, "201": { "description": "Message accepted; turn runs in background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageResult" } } } }, "202": { "description": "Wait deadline expired; turn still running (?wait=true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageResult" } } } }, "400": { "description": "Invalid ID format" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/participants": { "get": { "tags": [ "sessions" ], "summary": "GET /v1/sessions/{session_id}/participants - List session participants", "operationId": "list_session_participants", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session participant history", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionParticipant" } } } } }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "sessions" ], "summary": "POST /v1/sessions/{session_id}/participants - Add a session participant", "operationId": "add_session_participant", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSessionParticipantRequest" } } }, "required": true }, "responses": { "201": { "description": "Participant added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionParticipant" } } } }, "400": { "description": "Invalid participant request" }, "404": { "description": "Session or agent not found" }, "409": { "description": "Participant conflicts with current membership" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/participants/{participant_id}": { "delete": { "tags": [ "sessions" ], "summary": "DELETE /v1/sessions/{session_id}/participants/{participant_id} - Leave a participant", "operationId": "leave_session_participant", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } }, { "name": "participant_id", "in": "path", "description": "Participant ID (prefixed, e.g., part_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Participant left successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionParticipant" } } } }, "400": { "description": "Invalid ID" }, "404": { "description": "Session or participant not found" }, "409": { "description": "Host participant cannot leave through this endpoint" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/pin": { "put": { "tags": [ "sessions" ], "summary": "PUT /v1/sessions/{session_id}/pin - Pin session for current user", "operationId": "pin_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session pinned successfully" }, "400": { "description": "Invalid session ID" }, "401": { "description": "Authentication required" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "sessions" ], "summary": "DELETE /v1/sessions/{session_id}/pin - Unpin session for current user", "operationId": "unpin_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session unpinned successfully" }, "400": { "description": "Invalid session ID" }, "401": { "description": "Authentication required" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/question-answers": { "post": { "tags": [ "sessions" ], "summary": "POST /v1/sessions/{session_id}/question-answers", "description": "Answers the question set an agent raised with `ask_user`, and resumes the\npaused turn.", "operationId": "submit_question_answers", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionAnswersRequest" } } }, "required": true }, "responses": { "200": { "description": "Answer recorded and workflow resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionAnswersResponse" } } } }, "400": { "description": "Invalid session ID, or answers that do not match what was asked" }, "404": { "description": "Session or pending question set not found" }, "409": { "description": "Session is not waiting for tool results, or the question set was already answered" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/resolved-model": { "get": { "tags": [ "sessions" ], "summary": "GET /v1/sessions/{session_id}/resolved-model - Resolve the session's active model", "operationId": "get_session_resolved_model", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolved model for turns without a model override", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResolvedModelResponse" } } } }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/resources": { "get": { "tags": [ "session-resources" ], "summary": "List all resources registered in the session resource registry.", "operationId": "list_resources", "responses": { "200": { "description": "Session resources", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionResourceEntry" } } } } }, "404": { "description": "Session not found" } } } }, "/v1/sessions/{session_id}/sandbox": { "get": { "tags": [ "session-sandbox" ], "description": "Get the current session sandbox status (lease, runtime image, network access).", "operationId": "get_sandbox", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed sandbox status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionSandboxResponse" } } } }, "404": { "description": "Session not found" } } }, "post": { "tags": [ "session-sandbox" ], "description": "Manage the session sandbox lifecycle (start, stop, reset).", "operationId": "manage_sandbox", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageSessionSandboxRequest" } } }, "required": true }, "responses": { "200": { "description": "Managed sandbox lifecycle updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageSessionSandboxResponse" } } } }, "400": { "description": "Invalid action or sandbox not configured" }, "404": { "description": "Session not found" } } } }, "/v1/sessions/{session_id}/sse": { "get": { "tags": [ "events" ], "summary": "GET /v1/sessions/{session_id}/sse - Stream events (SSE notifications)", "description": "Establishes a Server-Sent Events (SSE) connection for real-time event streaming.\n\n## Connection Lifecycle Events\n\n- **connected**: Sent immediately when the stream is established.\n Data: `{\"status\":\"connected\"}`\n\n- **disconnecting**: Sent before the server closes the connection for graceful cycling.\n Data: `{\"reason\":\"connection_cycle\",\"retry_ms\":100}`\n Clients should reconnect immediately using the `since_id` of the last received event.\n\n## Connection Cycling\n\nConnections are automatically cycled every 5 minutes to prevent stale connections\nthrough proxies and load balancers. Before closing, the server sends a `disconnecting`\nevent so clients can reconnect seamlessly without missing events.\n\n## Retry Hints\n\nEach SSE event includes a `retry:` field (in milliseconds) that hints how long\nclients should wait before reconnecting if the connection is lost:\n- During active streaming: 100ms (fast reconnect)\n- During idle periods: increases with backoff up to 500ms\n- After `disconnecting` event: 100ms (immediate reconnect)\n\n## Resuming Streams\n\nUse the `since_id` query parameter to resume from a specific event. The server\nresolves the event ID to its sequence number and returns all subsequent events\nordered by sequence, ensuring reliable ordering even under concurrent writes.\n\n## Event Type Filtering\n\nUse `types` for positive filtering (only return these types) and `exclude` for\nnegative filtering (remove these types). When both are provided, `types` narrows\nfirst, then `exclude` removes from that set. Both accept only known event types\n(max 25 per parameter). Unknown types return 400.", "operationId": "stream_sse", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., sess_...)", "required": true, "schema": { "type": "string" } }, { "name": "since_id", "in": "query", "description": "Filter events with ID greater than this event ID (prefixed format: event_{32-hex})", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/eventId" } ] } }, { "name": "after_sequence", "in": "query", "description": "Forward cursor: replay durable events with `sequence` greater than this\nvalue before switching to live streaming. `after_sequence=0` replays the\nsession from its first event — that is what a client with an empty\nsnapshot must send, otherwise events written between its snapshot and\nthis subscription are never delivered. Mutually exclusive with `since_id`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } }, { "name": "types", "in": "query", "description": "Positive type filter: only return events matching these types (can be specified multiple times).\nWhen empty, all types are returned. Example: ?types=turn.started&types=turn.completed", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "exclude", "in": "query", "description": "Event types to exclude from the response (can be specified multiple times).\nApplied after `types` filter. Common delta events to exclude: output.message.delta, reason.thinking.delta", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Server-Sent Events stream. Each SSE message has the wire shape `event: \\nid: \\ndata: \\n\\n`, where `` is one of the event types in the `EventData` catalog (`turn.started`, `tool.completed`, `reason.thinking.delta`, …), `` is the event cursor (`event_{32-hex}` format, usable as `since_id` on reconnect), and `` is the body schema below — a serialized `Event` whose `data` field carries the event-type-specific payload defined in `EventData`. Lifecycle framing events (`connected`, `disconnecting`) use the same SSE shape but carry a minimal JSON object in `data` rather than a full `Event`. See `knowledge/execution/api-streaming.md` for the SSE convention.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "description": "Invalid session ID" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/storage/keys": { "get": { "tags": [ "session-storage" ], "summary": "GET /v1/sessions/{session_id}/storage/keys - List all key-value pairs", "operationId": "list_keys", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of key-value pairs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_KeyValueInfo" } } } }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/storage/secrets": { "get": { "tags": [ "session-storage" ], "summary": "GET /v1/sessions/{session_id}/storage/secrets - List all secrets (names only)", "operationId": "list_secrets", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of secrets (names only, no values)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_SecretInfo" } } } }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } }, "put": { "tags": [ "session-storage" ], "summary": "PUT /v1/sessions/{session_id}/storage/secrets - Batch set secrets", "description": "Encrypts and stores multiple secrets in a single request.\nExisting secrets with the same name are overwritten.", "operationId": "batch_set_secrets", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchSetSecretsRequest" } } }, "required": true }, "responses": { "200": { "description": "Secrets stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchSetSecretsResponse" } } } }, "400": { "description": "Bad request (encryption not configured or invalid input)" }, "404": { "description": "Session not found" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/storage/secrets/{name}": { "delete": { "tags": [ "session-storage" ], "description": "Delete a user-managed encrypted secret from one session.", "operationId": "delete_secret", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Secret name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session secret deleted" }, "404": { "description": "Session secret not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/sessions/{session_id}/tasks": { "get": { "tags": [ "session-tasks" ], "summary": "List background tasks owned by a session.", "operationId": "list_tasks", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Filter by state", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Filter by kind", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session tasks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionTask" } } } } }, "404": { "description": "Session not found" } } } }, "/v1/sessions/{session_id}/tasks/{task_id}": { "get": { "tags": [ "session-tasks" ], "summary": "Get one session task with its recent message thread.", "operationId": "get_task", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string" } }, { "name": "after_id", "in": "query", "description": "Return only messages after this message ID (exclusive cursor)", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max messages to return (default 50, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Session task detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTaskDetail" } } } }, "404": { "description": "Session or task not found" } } } }, "/v1/sessions/{session_id}/tasks/{task_id}/cancel": { "post": { "tags": [ "session-tasks" ], "summary": "Request cooperative cancellation of a session task.", "operationId": "cancel_task", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task with cancel intent recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTask" } } } }, "404": { "description": "Session or task not found" } } } }, "/v1/sessions/{session_id}/tasks/{task_id}/messages": { "post": { "tags": [ "session-tasks" ], "summary": "Send an inbound message to a session task.", "operationId": "post_task_message", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostTaskMessageBody" } } }, "required": true }, "responses": { "200": { "description": "Recorded task message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskMessage" } } } }, "400": { "description": "Empty message" }, "404": { "description": "Session or task not found" } } } }, "/v1/sessions/{session_id}/tasks/{task_id}/push-configs": { "get": { "tags": [ "session-tasks" ], "summary": "List per-task push-notification configs.", "operationId": "list_push_configs", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Push configs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaskPushConfig" } } } } }, "404": { "description": "Session or task not found" } } }, "post": { "tags": [ "session-tasks" ], "summary": "Create a per-task push-notification config.", "operationId": "create_push_config", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePushConfigBody" } } }, "required": true }, "responses": { "200": { "description": "Created push config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskPushConfig" } } } }, "400": { "description": "Invalid request (bad URL or event_filter)" }, "404": { "description": "Session or task not found" } } } }, "/v1/sessions/{session_id}/tasks/{task_id}/push-configs/{config_id}": { "delete": { "tags": [ "session-tasks" ], "summary": "Delete a per-task push-notification config.", "operationId": "delete_push_config", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } }, { "name": "task_id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "string" } }, { "name": "config_id", "in": "path", "description": "Push config ID (tpc_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Push config deleted" }, "404": { "description": "Session, task, or push config not found" } } } }, "/v1/sessions/{session_id}/tool-results": { "post": { "tags": [ "sessions" ], "summary": "POST /v1/sessions/{session_id}/tool-results - Submit client-side tool results", "description": "Accepts tool results executed by the client and resumes the agent workflow.\nSession must be in `waiting_for_tool_results` status.", "operationId": "submit_tool_results", "parameters": [ { "name": "session_id", "in": "path", "description": "Session ID (prefixed, e.g., session_...)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitToolResultsRequest" } } }, "required": true }, "responses": { "200": { "description": "Tool results accepted and workflow resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitToolResultsResponse" } } } }, "400": { "description": "Invalid session ID or request" }, "404": { "description": "Session not found" }, "409": { "description": "Session not in waiting_for_tool_results state" }, "500": { "description": "Internal server error" } } } }, "/v1/sessions/{session_id}/voice/calls": { "post": { "tags": [ "voice" ], "description": "Create a voice call attached to the session.", "operationId": "create_call", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCallRequest" } } }, "required": true }, "responses": { "200": { "description": "Realtime WebRTC call created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCallResponse" } } } } } } }, "/v1/sessions/{session_id}/voice/client-secret": { "post": { "tags": [ "voice" ], "description": "Create an ephemeral client secret for the voice channel.", "operationId": "create_client_secret", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceClientSecretRequest" } } }, "required": true }, "responses": { "200": { "description": "Realtime client secret created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceClientSecretResponse" } } } } } } }, "/v1/sessions/{session_id}/voice/{voice_connection_id}/attach": { "post": { "tags": [ "voice" ], "description": "Attach an external voice call to the session.", "operationId": "attach_call", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "voice_connection_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceAttachRequest" } } }, "required": true }, "responses": { "200": { "description": "Realtime sideband attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceAttachResponse" } } } } } } }, "/v1/sessions/{session_id}/voice/{voice_connection_id}/end": { "post": { "tags": [ "voice" ], "description": "End the in-flight voice call.", "operationId": "end_call", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "voice_connection_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceEndRequest" } } }, "required": true }, "responses": { "200": { "description": "Realtime voice connection ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceEndResponse" } } } } } } }, "/v1/skills": { "get": { "tags": [ "skills" ], "summary": "GET /v1/skills - List all skills", "operationId": "list_skills", "parameters": [ { "name": "search", "in": "query", "description": "Search by name or description (case-insensitive substring match).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "description": "Include archived skills. Deleted skills never appear in lists.", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "List of skills", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WithUrls_Skill" } } } } } }, "post": { "tags": [ "skills" ], "summary": "POST /v1/skills - Create skill from SKILL.md", "operationId": "create_skill", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillRequest" } } }, "required": true }, "responses": { "201": { "description": "Skill created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Skill" } } } }, "409": { "description": "Duplicate skill name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid SKILL.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/skills/config": { "get": { "tags": [ "skills" ], "summary": "GET /v1/skills/config", "operationId": "skill_config", "responses": { "200": { "description": "Resource config for skills", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceConfigResponse" } } } } } } }, "/v1/skills/upload": { "post": { "tags": [ "skills" ], "summary": "POST /v1/skills/upload - Create skill from ZIP archive", "operationId": "upload_skill", "responses": { "201": { "description": "Skill created from archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Skill" } } } }, "409": { "description": "Duplicate skill name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Archive too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid archive or SKILL.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/skills/usage": { "get": { "tags": [ "skills" ], "summary": "GET /v1/skills/usage - Count agents/harnesses referencing each skill", "operationId": "list_skills_usage", "responses": { "200": { "description": "Usage map keyed by skill id", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SkillUsage" }, "propertyNames": { "type": "string" } } } } } } } }, "/v1/skills/validate": { "post": { "tags": [ "skills" ], "summary": "POST /v1/skills/validate - Validate SKILL.md content", "operationId": "validate_skill", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateSkillRequest" } } }, "required": true }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillValidationResult" } } } } } } }, "/v1/skills/{skill_id}": { "get": { "tags": [ "skills" ], "summary": "GET /v1/skills/{skill_id} - Get skill by ID", "operationId": "get_skill", "parameters": [ { "name": "skill_id", "in": "path", "description": "Skill ID (prefixed, e.g., skill_...)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Skill" } } } }, "404": { "description": "Skill not found" } } }, "delete": { "tags": [ "skills" ], "summary": "DELETE /v1/skills/{skill_id} - Delete skill", "operationId": "delete_skill", "parameters": [ { "name": "skill_id", "in": "path", "description": "Skill ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Skill deleted" }, "404": { "description": "Skill not found" } } }, "patch": { "tags": [ "skills" ], "summary": "PATCH /v1/skills/{skill_id} - Update skill", "operationId": "update_skill", "parameters": [ { "name": "skill_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkillRequest" } } }, "required": true }, "responses": { "200": { "description": "Skill updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithUrls_Skill" } } } }, "404": { "description": "Skill not found" }, "409": { "description": "Duplicate skill name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid SKILL.md", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/skills/{skill_id}/content": { "get": { "tags": [ "skills" ], "summary": "GET /v1/skills/{skill_id}/content - Get full skill content", "operationId": "get_skill_content", "parameters": [ { "name": "skill_id", "in": "path", "description": "Skill ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillContent" } } } }, "404": { "description": "Skill not found" } } } }, "/v1/task-webhooks": { "get": { "tags": [ "task-webhooks" ], "summary": "List all task webhooks configured for the organization.", "operationId": "list_webhooks", "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_TaskWebhookResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — requires admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "task-webhooks" ], "summary": "Create a new task webhook for the organization.", "operationId": "create_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaskWebhookRequest" } } }, "required": true }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskWebhookResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — requires admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/task-webhooks/{webhook_id}": { "get": { "tags": [ "task-webhooks" ], "summary": "Get a single task webhook.", "operationId": "get_webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "Webhook public ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskWebhookResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — requires admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "task-webhooks" ], "summary": "Delete a task webhook.", "operationId": "delete_webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "Webhook public ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Webhook deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — requires admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "task-webhooks" ], "summary": "Update a task webhook.", "operationId": "update_webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "Webhook public ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskWebhookRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskWebhookResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — requires admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/tasks": { "get": { "tags": [ "session-tasks" ], "summary": "List background tasks across every session in the caller's org.", "operationId": "list_org_tasks", "parameters": [ { "name": "state", "in": "query", "description": "Filter by state", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Filter by kind", "required": false, "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "description": "Only tasks created at/after this RFC3339 timestamp", "required": false, "schema": { "type": "string" } }, { "name": "root_session_id", "in": "query", "description": "Only tasks whose owning session's delegation-tree root is this session", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max tasks, newest first (default 100, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Org tasks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionTask" } } } } } } } }, "/v1/user/mcp-connections": { "get": { "tags": [ "users" ], "description": "List the current user's cursor-paginated MCP OAuth connections in the selected organization.", "operationId": "list_mcp_connections", "parameters": [ { "name": "cursor", "in": "query", "description": "Continue after this opaque connection cursor.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Page size (default: 50, max: 100).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Cursor-paginated current user's MCP OAuth connections in the selected organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMcpConnectionsResponse" } } } }, "400": { "description": "Invalid cursor or limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/users": { "get": { "tags": [ "users" ], "summary": "GET /v1/users - List users in current organization", "description": "Lists users that belong to the current organization with optional search filtering.\nTM-TENANT-008: Enforces org isolation to prevent cross-tenant user enumeration.", "operationId": "list_users", "parameters": [ { "name": "search", "in": "query", "description": "Search by name or email", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of users in organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_User" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/v1/users/me": { "delete": { "tags": [ "users" ], "summary": "DELETE /v1/users/me - Delete current user's account", "description": "Hard-deletes the user and all associated data (API keys, memberships, tokens).\nThis action is irreversible.", "operationId": "delete_account", "responses": { "200": { "description": "Account deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found" }, "500": { "description": "Internal server error" } }, "x-side-effect": "irreversible" }, "patch": { "tags": [ "users" ], "summary": "PATCH /v1/users/me - Update current user's profile", "operationId": "update_profile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } }, "400": { "description": "Invalid request (empty name)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } } } }, "/v1/users/me/export": { "get": { "tags": [ "users" ], "summary": "GET /v1/users/me/export - Export current user's data", "description": "Returns all user-owned data in a structured JSON format for GDPR compliance.", "operationId": "export_user_data", "responses": { "200": { "description": "User data export", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportUserDataResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found" }, "500": { "description": "Internal server error" } } } }, "/v1/users/me/switch-org": { "post": { "tags": [ "users" ], "summary": "POST /v1/users/me/switch-org - Switch current organization", "description": "Sets a cookie with the selected organization. This org will be used for all\nsubsequent requests (including SSE connections via EventSource).\nThe user must be a member of the requested organization.", "operationId": "switch_org", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchOrgRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization switched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchOrgResponse" } } } }, "400": { "description": "Invalid organization ID format" }, "401": { "description": "Unauthorized" }, "404": { "description": "Organization not found or user is not a member" } } } }, "/v1/workspaces": { "get": { "tags": [ "workspace" ], "description": "List Workspaces.", "operationId": "list_workspaces", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Workspaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_Workspace" } } } } } }, "post": { "tags": [ "workspace" ], "description": "Create a Workspace.", "operationId": "create_workspace", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Name conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/workspaces/{workspace_id}": { "get": { "tags": [ "workspace" ], "description": "Get a Workspace by ID.", "operationId": "get_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "workspace" ], "description": "Archive a Workspace.", "operationId": "delete_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Archived" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "workspace" ], "description": "Update a Workspace.", "operationId": "update_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Name conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/workspaces/{workspace_id}/fs": { "get": { "tags": [ "workspace-filesystem" ], "summary": "GET /v1/workspaces/{workspace_id}/fs - Workspace root listing", "operationId": "get_root", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "List recursively", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Directory listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_FileInfo" } } } }, "404": { "description": "Workspace not found" }, "500": { "description": "Internal server error" } } } }, "/v1/workspaces/{workspace_id}/fs/_/copy": { "post": { "tags": [ "workspace-filesystem" ], "summary": "POST /v1/workspaces/{workspace_id}/fs/_/copy - Copy a file", "operationId": "copy_file", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyFileRequest" } } }, "required": true }, "responses": { "201": { "description": "Copied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFile" } } } }, "400": { "description": "Invalid request or cannot copy directories" }, "404": { "description": "Source not found" }, "409": { "description": "Destination exists" }, "500": { "description": "Internal server error" } } } }, "/v1/workspaces/{workspace_id}/fs/_/download/{path}": { "get": { "tags": [ "workspace-filesystem" ], "summary": "GET /v1/workspaces/{workspace_id}/fs/_/download/{path} - Download raw file bytes", "operationId": "download_path", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "File path. Wildcard route: nested paths are literal `/`-separated segments, not a single URL-encoded value.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw file bytes", "content": { "application/octet-stream": {} } }, "400": { "description": "Path points to a directory" }, "404": { "description": "File not found" }, "500": { "description": "Internal server error" } } } }, "/v1/workspaces/{workspace_id}/fs/_/grep": { "post": { "tags": [ "workspace-filesystem" ], "summary": "POST /v1/workspaces/{workspace_id}/fs/_/grep - Search files", "operationId": "grep_files", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrepRequest" } } }, "required": true }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_GrepResult" } } } }, "400": { "description": "Invalid regex pattern" }, "500": { "description": "Internal server error" } } } }, "/v1/workspaces/{workspace_id}/fs/_/move": { "post": { "tags": [ "workspace-filesystem" ], "summary": "POST /v1/workspaces/{workspace_id}/fs/_/move - Move/rename a file or directory", "operationId": "move_file", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveFileRequest" } } }, "required": true }, "responses": { "200": { "description": "Moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFile" } } } }, "400": { "description": "Invalid request" }, "404": { "description": "Source not found" }, "409": { "description": "Destination exists" }, "500": { "description": "Internal server error" } } } }, "/v1/workspaces/{workspace_id}/fs/_/preview/{path}": { "get": { "tags": [ "workspace-filesystem" ], "summary": "GET /v1/workspaces/{workspace_id}/fs/_/preview/{path} - Sandboxed HTML render", "description": "Serves an HTML file as a `text/html` document carrying a strict `sandbox`\nCSP (TM-WEB-010) so the file viewer can render it — with JavaScript — inside\nan iframe without exposing everruns cookies, storage, the parent DOM, or\ntop-frame navigation. Only `.html`/`.htm` files are eligible; everything else\nreturns 415 (use the download endpoint instead).", "operationId": "preview_path", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "HTML file path. Wildcard route: nested paths are literal `/`-separated segments, not a single URL-encoded value.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sandboxed HTML document", "content": { "text/html": {} } }, "400": { "description": "Path points to a directory" }, "404": { "description": "File not found" }, "415": { "description": "File is not an HTML document" }, "500": { "description": "Internal server error" } } } }, "/v1/workspaces/{workspace_id}/fs/_/stat": { "post": { "tags": [ "workspace-filesystem" ], "summary": "POST /v1/workspaces/{workspace_id}/fs/_/stat - File metadata", "operationId": "stat_file", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatRequest" } } }, "required": true }, "responses": { "200": { "description": "File metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileStat" } } } }, "404": { "description": "Not found" }, "500": { "description": "Internal server error" } } } }, "/v1/workspaces/{workspace_id}/fs/{path}": { "get": { "tags": [ "workspace-filesystem" ], "summary": "GET /v1/workspaces/{workspace_id}/fs/{path} - Read file or list directory", "operationId": "get_path", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "File or directory path. Wildcard route: nested paths are literal `/`-separated segments, not a single URL-encoded value.", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "List recursively", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "File content or directory listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetResponse" } } } }, "404": { "description": "Not found" }, "500": { "description": "Internal server error" } } }, "put": { "tags": [ "workspace-filesystem" ], "summary": "PUT /v1/workspaces/{workspace_id}/fs/{path} - Update file content", "operationId": "update_path", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "File path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFileRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFile" } } } }, "400": { "description": "Invalid request" }, "404": { "description": "Not found" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "workspace-filesystem" ], "summary": "POST /v1/workspaces/{workspace_id}/fs/{path} - Create file or directory", "operationId": "create_path", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "File or directory path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFileRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFile" } } } }, "400": { "description": "Invalid request" }, "409": { "description": "Already exists" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "workspace-filesystem" ], "summary": "DELETE /v1/workspaces/{workspace_id}/fs/{path} - Delete file or directory", "operationId": "delete_path", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID (wsp_<32-hex>)", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "File or directory path", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Delete recursively", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFileResponse" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Cannot delete readonly content" }, "500": { "description": "Internal server error" } } } } }, "components": { "schemas": { "AcceptInviteResponse": { "type": "object", "description": "Accept response: where the caller now has membership.", "required": [ "org_id", "role" ], "properties": { "org_id": { "type": "string" }, "role": { "type": "string" } } }, "ActCompletedData": { "type": "object", "description": "Data for act.completed event", "required": [ "completed", "success_count", "error_count" ], "properties": { "completed": { "type": "boolean", "description": "Whether all tool calls completed" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Duration of the act phase in milliseconds", "minimum": 0 }, "error_count": { "type": "integer", "format": "int32", "description": "Number of failed tool calls", "minimum": 0 }, "headline": { "type": [ "string", "null" ], "description": "Human-readable headline for the completed batch" }, "success_count": { "type": "integer", "format": "int32", "description": "Number of successful tool calls", "minimum": 0 } } }, "ActStartedData": { "type": "object", "description": "Data for act.started event", "required": [ "tool_calls" ], "properties": { "headline": { "type": [ "string", "null" ], "description": "Human-readable headline for the batch" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCallSummary" }, "description": "Tool calls to be executed" } } }, "AddSessionParticipantRequest": { "type": "object", "description": "Request to add a participant to a session.", "required": [ "kind" ], "properties": { "agent_id": { "type": [ "string", "null" ], "description": "Agent to add when `kind` is `agent`.", "example": "agent_01933b5a00007000800000000000001" }, "kind": { "$ref": "#/components/schemas/SessionParticipantKind", "description": "Participant kind to add." }, "role": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SessionParticipantRole", "description": "Participant role. Omit for ordinary members. Host assignment is managed by session creation." } ] } } }, "Agent": { "type": "object", "description": "Agent configuration for agentic loop.\nAn agent defines the behavior and capabilities of an AI assistant.", "required": [ "id", "name", "system_prompt", "harness_id", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the agent was archived.", "example": "2026-05-26T00:00:00Z" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities enabled for this agent with per-agent configuration.\nCapabilities add tools and system prompt modifications." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was created.", "example": "2026-04-01T10:00:00Z" }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model ID for this agent.\nCan be overridden at the session level.", "example": "model_01933b5a00007000800000000000001" }, "default_version_id": { "type": [ "string", "null" ], "description": "Default immutable version used by deployments that choose the default policy.", "example": "agentver_01933b5a00007000800000000000001" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the agent was deleted.", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the agent does.", "example": "Handles refund and shipping questions; escalates billing disputes." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI (e.g. \"Customer Support Agent\").\nFalls back to `name` when absent.", "example": "Customer Support Agent" }, "exposed": { "type": "boolean", "description": "Whether any endpoint on this agent is currently live. Derived from the\nendpoint rows on read and never stored: a stored flag would be a second\nwriter for state the endpoints already own." }, "exposures_suspended": { "type": "boolean", "description": "Incident switch: when true, no endpoint on this agent accepts traffic\n(EVE-1007). Distinct from archiving — it leaves per-endpoint status\nuntouched so clearing it restores exactly the previously live set." }, "forked_from_agent_id": { "type": [ "string", "null" ], "description": "Source agent for a forked agent.", "example": "agent_01933b5a00007000800000000000001" }, "forked_from_version_id": { "type": [ "string", "null" ], "description": "Source version for a forked agent.", "example": "agentver_01933b5a00007000800000000000001" }, "harness_id": { "type": "string", "description": "Harness that supplies the base execution environment for this agent.", "example": "harness_01933b5a00007000800000000000001" }, "id": { "type": "string", "description": "External identifier (agent_<32-hex>). Shown as \"id\" in API.\nClient-supplied or auto-generated.", "example": "agent_01933b5a000070008000000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this agent." }, "intro_markdown": { "type": [ "string", "null" ], "description": "Optional Markdown intro rendered as an intro box at the top of a fresh\nPlatform Chat thread. Images are allowed. Wins over the harness intro.\nHidden once the user inputs.", "example": "Hey, I'm Ava. Ask me anything about your account." }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this agent.", "example": 50, "minimum": 0 }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this agent and inherited by its sessions." }, "name": { "type": "string", "description": "Name, unique per org (e.g. \"customer-support\").", "example": "customer-support" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs agent sessions can reach.\nMerged with harness and session layers (allowed: intersect, blocked: union)." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "root_agent_id": { "type": [ "string", "null" ], "description": "Root agent lineage identifier for grouping fork families.", "example": "agent_01933b5a00007000800000000000001" }, "short_description": { "type": [ "string", "null" ], "description": "Optional one-line description in simplified Markdown, shown below the\nchat title once the intro is hidden. Wins over the harness value.", "example": "Answers account questions in seconds." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. Win over the\nharness starters when non-empty." }, "status": { "$ref": "#/components/schemas/AgentStatus", "description": "Current lifecycle status of the agent." }, "system_prompt": { "type": "string", "description": "System prompt that defines the agent's behavior.\nSent as the first message in every conversation.", "example": "You are a friendly customer support agent for Acme Corp. Verify orders before issuing refunds. Escalate any billing disputes to a human." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering agents.", "example": [ "support", "production" ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools registered for this agent.\nThese tools are executed by the client, not the server." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was last updated.", "example": "2026-05-20T14:00:00Z" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative token usage across all sessions for this agent." } ] } } }, "AgentAnalysisResponse": { "type": "object", "description": "Response from on-demand agent analysis (built-in rules + LLM checkers)", "required": [ "findings" ], "properties": { "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "description": "Advisory findings, built-in and LLM-sourced (knowledge/evaluation/agent-checks.md)" } } }, "AgentCapabilityConfig": { "type": "object", "description": "Per-agent capability configuration\n\nAssociates a capability with an agent, including optional per-agent configuration.\nThe config field allows the same capability to behave differently per-agent.", "required": [ "ref" ], "properties": { "config": { "description": "Per-agent configuration for this capability (capability-specific)" }, "ref": { "type": "string", "description": "Reference to the capability ID" } } }, "AgentCredentialBinding": { "type": "object", "description": "Metadata for a write-only credential bound to one agent and MCP tool parameter.", "required": [ "id", "agent_id", "mcp_server_name", "mcp_server_url", "tool_name", "parameter_name", "label", "configured", "created_at", "updated_at", "setup_url" ], "properties": { "agent_id": { "type": "string", "description": "Agent that exclusively owns and may use this credential.", "example": "agent_01933b5a000070008000000000000001" }, "configured": { "type": "boolean", "description": "Whether an encrypted value has been provisioned.", "example": true }, "created_at": { "type": "string", "description": "RFC 3339 creation time.", "example": "2026-08-08T16:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Optional explanation of why the credential is needed.", "example": "Delivers scheduled status notifications" }, "id": { "type": "string", "format": "uuid", "description": "Stable credential binding identifier.", "example": "01933b5a-0000-7000-8000-000000000001" }, "label": { "type": "string", "description": "Human-readable credential label.", "example": "Visti channel key" }, "mcp_server_name": { "type": "string", "description": "Name of the attached MCP server.", "example": "visti" }, "mcp_server_url": { "type": "string", "description": "Exact MCP endpoint authorized to receive the credential.", "example": "https://visti.sh/mcp" }, "parameter_name": { "type": "string", "description": "Top-level tool argument injected by the server.", "example": "channel_key" }, "setup_url": { "type": "string", "description": "Relative UI route where the user can securely provision the value.", "example": "/agents/agent_01933b5a000070008000000000000001?tab=credentials" }, "tool_name": { "type": "string", "description": "MCP tool whose outbound call receives the credential.", "example": "visti_send" }, "updated_at": { "type": "string", "description": "RFC 3339 last-update time.", "example": "2026-08-08T16:05:00Z" } } }, "AgentHarnessSource": { "type": "string", "enum": [ "explicit", "organization_default" ] }, "AgentHarnessStatus": { "type": "string", "enum": [ "active", "archived", "deleted", "unresolved" ] }, "AgentHarnessSummary": { "type": "object", "description": "Harness that a newly created session for this agent will resolve to.", "required": [ "source", "status" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/AgentHarnessSource" }, "status": { "$ref": "#/components/schemas/AgentHarnessStatus" } } }, "AgentMcpAttachment": { "type": "object", "description": "Effective MCP attachment projected for an agent and the current caller.", "required": [ "name", "source", "source_label", "overridden_sources", "acts_as", "header_names", "tools_available", "tools", "state", "action", "can_revoke", "editable" ], "properties": { "action": { "$ref": "#/components/schemas/AgentMcpAttachmentAction", "description": "Connection action available to the current caller." }, "acts_as": { "$ref": "#/components/schemas/McpServerActsAs", "description": "Identity whose connection is used when the attachment calls the MCP server." }, "can_revoke": { "type": "boolean", "description": "Whether the current caller can revoke the active connection." }, "connected_as": { "type": [ "string", "null" ], "description": "Connected account name, or the preset name when the provider did not supply one." }, "connection_provider": { "type": [ "string", "null" ], "description": "OAuth provider key used to create or revoke the attachment connection." }, "contributor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentMcpAttachmentContributor", "description": "Capability that contributed the attachment, when the winning source is a capability." } ] }, "editable": { "type": "boolean", "description": "Whether the attachment is defined directly on the agent and can be removed there." }, "header_names": { "type": "array", "items": { "type": "string" }, "description": "Header names configured for the endpoint; secret header values are omitted." }, "name": { "type": "string", "description": "Logical attachment name used in the agent's MCP configuration." }, "overridden_sources": { "type": "array", "items": { "$ref": "#/components/schemas/AgentMcpAttachmentSourceInfo" }, "description": "Lower-precedence configuration layers overridden by this attachment." }, "preset_id": { "type": [ "string", "null" ], "description": "ID of the active catalog preset when the reference resolves." }, "preset_name": { "type": [ "string", "null" ], "description": "Catalog preset name referenced by the attachment, including a missing preset." }, "source": { "$ref": "#/components/schemas/AgentMcpAttachmentSource", "description": "Highest-precedence configuration layer that supplied this attachment." }, "source_label": { "type": "string", "description": "Human-readable name of the winning capability, harness, or agent layer." }, "state": { "$ref": "#/components/schemas/AgentMcpAttachmentState", "description": "Current preset and connection availability." }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Cached names of tools exposed by the MCP server." }, "tools_available": { "type": "boolean", "description": "Whether at least one cached tool name is available." }, "url": { "type": [ "string", "null" ], "description": "Effective MCP endpoint URL from the catalog preset or inline configuration." } } }, "AgentMcpAttachmentAction": { "type": "string", "description": "Action the current caller can take to make an MCP attachment usable.", "enum": [ "none", "connect", "authorize", "ask_admin" ] }, "AgentMcpAttachmentContributor": { "type": "object", "description": "Capability that contributed an effective MCP attachment.", "required": [ "id", "name", "href" ], "properties": { "href": { "type": "string", "description": "UI path for the capability detail page." }, "id": { "type": "string", "description": "Canonical capability ID." }, "name": { "type": "string", "description": "Human-readable capability name." } } }, "AgentMcpAttachmentSource": { "type": "string", "description": "Configuration layer that supplied an effective MCP attachment.", "enum": [ "capability", "harness", "agent" ] }, "AgentMcpAttachmentSourceInfo": { "type": "object", "description": "Configuration layer that was overridden by the effective MCP attachment.", "required": [ "source", "source_label" ], "properties": { "source": { "$ref": "#/components/schemas/AgentMcpAttachmentSource", "description": "Overridden configuration layer." }, "source_label": { "type": "string", "description": "Human-readable name of the overridden capability, harness, or agent layer." } } }, "AgentMcpAttachmentState": { "type": "string", "description": "Availability state of an effective MCP attachment.", "enum": [ "ready", "connection_missing", "preset_missing" ] }, "AgentMessage": { "type": "object", "required": [ "role", "text" ], "properties": { "role": { "type": "string" }, "text": { "type": "string" } } }, "AgentPreviewResponse": { "type": "object", "description": "Response showing the final agent shape after applying capabilities", "required": [ "system_prompt", "tools", "findings" ], "properties": { "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "description": "Advisory findings from built-in checks (knowledge/evaluation/agent-checks.md)" }, "system_prompt": { "type": "string", "description": "The full system prompt with capability additions prepended" }, "tools": { "type": "array", "items": { "type": "object" }, "description": "All tool definitions from capabilities" } } }, "AgentStatus": { "type": "string", "description": "Agent lifecycle status.\n- `active`: Agent is available for use\n- `archived`: Agent is hidden from listings and cannot be modified or assigned\n- `deleted`: Agent is a tombstone kept only for historical references", "enum": [ "active", "archived", "deleted" ], "example": "active" }, "AgentTrigger": { "type": "object", "description": "AgentTrigger is a durable, agent-owned invocation trigger.", "required": [ "id", "agent_id", "trigger_type", "config", "enabled", "created_at", "updated_at" ], "properties": { "agent_id": { "type": "string", "description": "Agent that owns this trigger.", "example": "agent_01933b5a000070008000000000000001" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Archive timestamp." }, "config": { "description": "Type-specific configuration (parsed via typed accessors)." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Delete timestamp." }, "enabled": { "type": "boolean", "description": "Whether the trigger is currently active." }, "id": { "type": "string", "description": "External identifier (trg_<32-hex>). Shown as `id` in API.", "example": "trg_01933b5a000070008000000000000001" }, "ingress_id": { "type": [ "string", "null" ], "description": "Stable HTTP ingress identifier for trigger types that accept requests." }, "trigger_type": { "$ref": "#/components/schemas/AgentTriggerType", "description": "The kind of event that fires this trigger." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp." } } }, "AgentTriggerRun": { "type": "object", "description": "One recent durable execution of an agent schedule trigger.", "required": [ "id", "status", "scheduled_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the execution completed, when terminal." }, "error": { "type": [ "string", "null" ], "description": "Failure message for an unsuccessful execution." }, "id": { "type": "string", "description": "Durable execution identifier." }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Time the execution was scheduled." }, "status": { "type": "string", "description": "Current durable execution status." } } }, "AgentTriggerType": { "type": "string", "description": "The kind of event that fires an agent trigger.", "enum": [ "schedule", "webhook" ] }, "AgentVersion": { "type": "object", "description": "Immutable snapshot of an Agent's authored and resolved runtime config.", "required": [ "id", "agent_id", "version_number", "semver_major", "semver_minor", "semver_patch", "version", "is_published", "change_kind", "config_hash", "authored_config", "resolved_config", "created_at" ], "properties": { "agent_id": { "type": "string", "description": "Owning agent's prefixed public identifier.", "example": "agent_01933b5a000070008000000000000001" }, "authored_config": { "type": "object", "description": "User-authored agent configuration JSON, exactly as submitted. Capabilities, MCP refs, model selection live here." }, "change_kind": { "$ref": "#/components/schemas/AgentVersionChangeKind", "description": "Classification of why this version was created (manual publish, automatic draft, rollback, fork, etc.)." }, "config_hash": { "type": "string", "description": "Stable hash of `resolved_config` used to deduplicate adjacent identical snapshots.", "example": "blake3:9f1e2a4c3d5b6e8a0b2c4d6e8f0a1b3c5d7e9f0a1b2c4d6e8f0a1b2c4d6e8f0a" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this version was created (RFC 3339).", "example": "2026-04-20T14:22:00Z" }, "created_by_principal_id": { "type": [ "string", "null" ], "description": "Identity of the principal (user or agent identity) that created this version. `None` for system-generated snapshots." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "agentver_01933b5a000070008000000000000001" }, "is_published": { "type": "boolean", "description": "Whether this version was explicitly published by a user. Published versions are user-controlled semver releases; unpublished rows are automatic draft snapshots kept for audit and rollback.", "example": true }, "parent_version_id": { "type": [ "string", "null" ], "description": "Version this one was forked or branched from, if any." }, "resolved_config": { "type": "object", "description": "Resolved configuration after applying harness, capability, and platform layers. This is what the runtime executes against." }, "semver_major": { "type": "integer", "format": "int32", "description": "Semantic version major component.", "example": 1 }, "semver_minor": { "type": "integer", "format": "int32", "description": "Semantic version minor component.", "example": 4 }, "semver_patch": { "type": "integer", "format": "int32", "description": "Semantic version patch component.", "example": 2 }, "source_version_id": { "type": [ "string", "null" ], "description": "When this version is a copy of another version (e.g. a manual rollback), the original source. `None` for ordinary snapshots." }, "summary": { "type": [ "string", "null" ], "description": "Human-readable summary of changes in this version (release notes). `None` if not provided.", "example": "Switched default model to claude-sonnet-4-6; added refund-runbook capability." }, "version": { "type": "string", "description": "Combined semver string for display (e.g. `1.4.2`).", "example": "1.4.2" }, "version_number": { "type": "integer", "format": "int32", "description": "Monotonic per-agent version sequence number (1, 2, 3, ...). Increments on every snapshot.", "example": 7 } } }, "AgentVersionChangeKind": { "type": "string", "description": "Reason a version was created. Stored as lower_snake_case text.\nOne of `auto`, `manual`, `patch`, `minor`, `major`, `import`, `rollback`, `fork`.", "enum": [ "auto", "manual", "patch", "minor", "major", "import", "rollback", "fork" ], "example": "manual" }, "AgentVersionDiffResponse": { "type": "object", "description": "Response body for agent version diff.", "required": [ "from_version_id", "to_version_id", "authored_diff", "resolved_diff" ], "properties": { "authored_diff": {}, "from_version_id": { "$ref": "#/components/schemas/agentverId" }, "resolved_diff": {}, "to_version_id": { "$ref": "#/components/schemas/agentverId" } } }, "AgentVersionPolicy": { "type": "string", "description": "How an App resolves the Agent version it runs.", "enum": [ "default", "latest", "pinned" ], "example": "pinned" }, "AgentWithCounts": { "allOf": [ { "$ref": "#/components/schemas/Agent" }, { "type": "object", "required": [ "session_count", "app_count", "effective_harness" ], "properties": { "app_count": { "type": "integer", "format": "int64", "minimum": 0 }, "effective_harness": { "$ref": "#/components/schemas/AgentHarnessSummary" }, "session_count": { "type": "integer", "format": "int64", "minimum": 0 } } } ], "description": "Agent list/detail payload with relationship counts and resolved harness metadata." }, "AllowedAction": { "type": "object", "description": "Agent-actionable link describing a follow-up the caller can take. Used in\ntwo contexts:\n\n* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like\n `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows\n the right next call after a 4xx/429.\n* **Entity hypermedia** — `WithUrls.allowed_actions` carries state-aware\n `rel`s like `cancel`, `events`, `self`, `update` on the entity itself\n so the agent can follow links instead of reconstructing routes from\n prose.\n\nThe shape is intentionally identical across both contexts; the closed\n`rel` vocabulary documented in `knowledge/execution/api-conventions.md` distinguishes\nthem.", "required": [ "rel" ], "properties": { "hint": { "type": [ "string", "null" ], "description": "Short, agent-readable hint (e.g. \"Shorten 'name' to <= 200 chars.\",\n\"Cancel the active turn for this session.\")." }, "href": { "type": [ "string", "null" ], "description": "Absolute (preferred) or relative URL the caller may invoke\ndirectly. **Always present on entity hypermedia actions**\n(`WithUrls.allowed_actions`); **optional on error-recovery\nactions** (`ErrorResponse.allowed_actions`) where the matching\n`operation_id` is enough and the URI is implicit from the failed\ncall." }, "method": { "type": [ "string", "null" ], "description": "HTTP method to use against `href`. Required for entity hypermedia\nactions; usually omitted on error-recovery actions where the same\noperation is retried with its original method.", "example": "POST" }, "operation_id": { "type": [ "string", "null" ], "description": "OpenAPI `operationId` the caller should invoke. Lets an MCP client\nresolve the call without parsing `href`." }, "rel": { "type": "string", "description": "Link relation describing the action. Closed vocabulary documented\nin `knowledge/execution/api-conventions.md` — examples: `self`, `cancel`, `pause`,\n`resume`, `events`, `retry`, `retry-later`, `unarchive`,\n`get-existing`, `delete`, `update`." }, "schema_ref": { "type": [ "string", "null" ], "description": "OpenAPI `$ref` to the request-body schema, when the action takes one\n(e.g. `#/components/schemas/UpdateSessionRequest`). Lets a tool-calling\nagent fetch the input shape without scanning the whole spec." } } }, "AnnotationSource": { "type": "object", "description": "The source a [`TextAnnotation`] points to.", "required": [ "uri" ], "properties": { "location": { "description": "Provenance within the document (line / char / page / block ranges),\nreusing the retrieval `location` JSONB shape." }, "snippet": { "type": [ "string", "null" ], "description": "Trimmed passage that backs the claim. Display-only; never relied on for\nprompt reconstruction.", "example": "The control plane owns durable state." }, "title": { "type": [ "string", "null" ], "description": "Human-readable source title, when known.", "example": "Architecture Overview" }, "uri": { "type": "string", "description": "Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an\n`https://` URL).", "example": "github://owner/repo@main/docs/x.md" } } }, "ApiKeyConnectionRequest": { "type": "object", "description": "Request body for API-key-based connections (e.g., Brave Search)", "required": [ "api_key" ], "properties": { "api_key": { "type": "string" } } }, "App": { "type": "object", "description": "App configuration for deploying agents to channels.\nAn app binds a harness and optional agent to distribution channels with a\npublish lifecycle.", "required": [ "id", "name", "harness_id", "owner_principal_id", "status", "created_at", "updated_at" ], "properties": { "agent_id": { "type": [ "string", "null" ], "description": "Optional ID of the agent to use (format: agent_{32-hex}).", "example": "agent_01933b5a00007000800000000000001" }, "agent_identity_id": { "type": [ "string", "null" ], "description": "Optional virtual identity that represents the app in unattended/channel execution.", "example": "identity_01933b5a00007000800000000000001" }, "agent_version_id": { "type": [ "string", "null" ], "description": "Pinned agent version. Required when policy is `pinned`.", "example": "agentver_01933b5a00007000800000000000001" }, "agent_version_policy": { "$ref": "#/components/schemas/AgentVersionPolicy", "description": "Version resolution policy for the optional agent." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the app was archived." }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/AppChannel" }, "description": "Distribution channels attached to this app." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the app was created." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the app was deleted." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the app does." }, "effective_owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Effective human owner summary." } ] }, "harness_id": { "type": "string", "description": "ID of the harness to use (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "id": { "type": "string", "description": "External identifier (app_<32-hex>). Shown as \"id\" in API.", "example": "app_01933b5a000070008000000000000001" }, "name": { "type": "string", "description": "Display name of the app." }, "owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Owning principal summary." } ] }, "owner_principal_id": { "type": "string", "description": "Owning principal for this app.", "example": "principal_01933b5a000070008000000000000001" }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the app was last published." }, "resolved_owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Denormalized effective human owner of the owning principal lineage." }, "status": { "$ref": "#/components/schemas/AppStatus", "description": "Current lifecycle status." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the app was last updated." } } }, "AppChannel": { "type": "object", "description": "A single distribution channel attached to an App.\nEach channel has its own type, config, and lifecycle status.", "required": [ "id", "channel_type", "created_at", "updated_at" ], "properties": { "auth": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AppEndpointAuthConfig", "description": "Authentication policy for this endpoint." } ] }, "channel_config": { "description": "Channel-specific configuration (validated per channel type)." }, "channel_type": { "$ref": "#/components/schemas/ChannelType", "description": "Channel type (e.g. slack)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this channel was created." }, "enabled": { "type": "boolean", "description": "Whether this channel is enabled." }, "id": { "type": "string", "description": "External identifier (appchan_<32-hex>). Shown as \"id\" in API.", "example": "appchan_01933b5a000070008000000000000001" }, "status": { "$ref": "#/components/schemas/EndpointStatus", "description": "Per-endpoint lifecycle. Authoritative for ingress (EVE-1007); `enabled`\nis retained for the App API's existing shape." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this channel was last updated." } } }, "AppEndpointAuthConfig": { "type": "object", "description": "Authentication config for one App endpoint/channel.", "required": [ "mode" ], "properties": { "mode": { "$ref": "#/components/schemas/AppEndpointAuthMode" }, "provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AppEndpointAuthProviderConfig" } ] }, "requirements": { "$ref": "#/components/schemas/AppEndpointAuthRequirements" } }, "example": { "mode": "api_key", "requirements": { "audiences": [ "everruns-api" ], "scopes": [ "app:invoke" ] } } }, "AppEndpointAuthMode": { "type": "string", "description": "App-published endpoint authentication mode.\n\nStored on `AppChannel.auth` so users can protect one endpoint without first\ncreating org-level identity-provider state.", "enum": [ "anonymous", "shared_secret", "api_key", "google_oidc", "oidc", "oauth2_introspection", "http_basic", "mtls" ] }, "AppEndpointAuthProviderConfig": { "oneOf": [ { "type": "object", "required": [ "client_id", "type" ], "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" } }, "client_id": { "type": "string" }, "type": { "type": "string", "enum": [ "google_oidc" ] } } }, { "type": "object", "required": [ "issuer", "type" ], "properties": { "issuer": { "type": "string" }, "jwks_url": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "oidc" ] } } }, { "type": "object", "required": [ "introspection_url", "type" ], "properties": { "client_id": { "type": [ "string", "null" ] }, "client_secret": { "type": [ "string", "null" ] }, "client_secret_configured": { "type": "boolean" }, "introspection_url": { "type": "string" }, "type": { "type": "string", "enum": [ "oauth2_introspection" ] } } }, { "type": "object", "required": [ "username", "type" ], "properties": { "password": { "type": [ "string", "null" ] }, "password_configured": { "type": "boolean" }, "password_hash": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "http_basic" ] }, "username": { "type": "string" } } }, { "type": "object", "required": [ "header_name", "type" ], "properties": { "allowed_values": { "type": "array", "items": { "type": "string" } }, "header_name": { "type": "string" }, "proxy_secret": { "type": [ "string", "null" ], "description": "Shared secret the trusted proxy includes in `proxy_secret_header`.\nWrite-only: redacted in GET responses. See TM-AUTH-021." }, "proxy_secret_configured": { "type": "boolean" }, "proxy_secret_header": { "type": [ "string", "null" ], "description": "Header the trusted reverse proxy uses to prove its identity.\nRequired. Configs without this field fail closed at verification time." }, "type": { "type": "string", "enum": [ "mtls" ] } } } ], "description": "OIDC/OAuth/basic/mTLS provider details for one App endpoint." }, "AppEndpointAuthRequirements": { "type": "object", "description": "Claim and credential requirements common to App endpoint auth providers.", "properties": { "audiences": { "type": "array", "items": { "type": "string" }, "description": "JWT `aud` values to require on inbound tokens. Empty list disables audience checking." }, "claims": { "type": "object", "description": "Arbitrary claim equality predicates. Empty map disables claim filtering.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Allowlist of email/identifier domains. Empty list disables domain filtering." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "Allowlist of group memberships (from `groups` claim). Empty list disables group filtering." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scope strings to require (space-delimited per scope entry). Empty list disables scope checking." }, "subjects": { "type": "array", "items": { "type": "string" }, "description": "Allowlist of `sub` claim values. Empty list disables subject filtering." } } }, "AppStatus": { "type": "string", "description": "App lifecycle status.\n- `draft`: App is configured but not accepting requests\n- `published`: App is live, accepting incoming requests\n- `archived`: App is hidden from listings and cannot be modified or assigned\n- `deleted`: App is a tombstone kept only for historical references", "enum": [ "draft", "published", "archived", "deleted" ], "example": "published" }, "BTreeMap": { "type": "object", "additionalProperties": { "type": "object", "description": "Session-, agent-, or harness-scoped remote MCP server configuration.\n\nThis intentionally mirrors the `mcpServers` object shape used by common MCP\nclient config files while staying within Everruns' current remote-HTTP-only\nsupport.", "properties": { "actsAs": { "$ref": "#/components/schemas/McpServerActsAs", "description": "Identity whose grant this attachment requests." }, "args": { "type": "array", "items": { "type": "string" }, "description": "Arguments passed to the stdio `command`." }, "auth_mode": { "$ref": "#/components/schemas/McpServerAuthMode", "description": "Authentication mode used when executing tools from this scoped server." }, "command": { "type": [ "string", "null" ], "description": "Executable to spawn for a stdio transport server." }, "env": { "type": "object", "description": "Environment variables set for the stdio `command`.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "headers": { "type": "object", "description": "Additional HTTP headers sent on MCP requests (HTTP transport only).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "oauth_provider_id": { "type": [ "string", "null" ], "description": "Provider id used to resolve a user-scoped bearer token." }, "protocol_mode": { "$ref": "#/components/schemas/McpProtocolMode", "description": "Protocol-era adoption policy for the MCP client (`auto` negotiates)." }, "tool_discovery": { "type": "boolean", "description": "Whether to discover tool definitions live from this server." }, "type": { "$ref": "#/components/schemas/McpServerTransportType", "description": "MCP transport type. Only remote HTTP is supported today." }, "url": { "type": "string", "description": "URL of the remote MCP server endpoint. Required for HTTP transport;\nempty/ignored for stdio." }, "use": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpServerPresetRef", "description": "Organization catalog preset that supplies transport and authentication policy." } ] } } }, "propertyNames": { "type": "string" } }, "BackgroundProgress": { "type": "object", "description": "Structured progress reported by background tools.", "properties": { "current": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "label": { "type": [ "string", "null" ] }, "total": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "unit": { "type": [ "string", "null" ] } } }, "BatchSetSecretsRequest": { "type": "object", "description": "Batch secret set request", "required": [ "secrets" ], "properties": { "secrets": { "type": "object", "description": "Map of secret names to values. Names are case-sensitive; values are stored encrypted\nand never returned by list/read endpoints. Existing keys are overwritten.\nExample: `{\"OPENAI_API_KEY\": \"sk-...\", \"GITHUB_TOKEN\": \"ghp_...\"}`.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "BatchSetSecretsResponse": { "type": "object", "description": "Batch secret set response", "required": [ "count" ], "properties": { "count": { "type": "integer", "description": "Number of secrets stored", "minimum": 0 } } }, "Budget": { "type": "object", "description": "Budget — a stored spending cap for a platform subject.", "required": [ "id", "organization_id", "subject_type", "subject_id", "currency", "limit", "balance", "status", "created_at", "updated_at" ], "properties": { "balance": { "type": "number", "format": "double", "description": "Current remaining balance (limit minus consumed)." }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "description": "Currency: \"usd\", \"tokens\", \"credits\", or custom." }, "id": { "type": "string", "example": "bdgt_01933b5a00007000800000000000001" }, "limit": { "type": "number", "format": "double", "description": "Hard limit — budget ceiling." }, "metadata": { "description": "Arbitrary metadata." }, "organization_id": { "type": "string" }, "period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BudgetPeriod", "description": "Optional period for recurring budgets." } ] }, "period_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the current period started (used to detect period rollover for\n`Duration` / `Rolling` periods, and to display \"resets at\" in the UI).\n`None` for budgets without a period." }, "soft_limit": { "type": [ "number", "null" ], "format": "double", "description": "Soft limit — triggers pause/warn when balance drops below this." }, "status": { "$ref": "#/components/schemas/BudgetStatus" }, "subject_id": { "type": "string", "description": "Public ID of the subject entity." }, "subject_type": { "$ref": "#/components/schemas/BudgetSubjectType" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BudgetCheckResult": { "type": "object", "description": "Result of checking all budgets for a session.", "required": [ "action" ], "properties": { "action": { "type": "string", "description": "Most restrictive action across all budgets." }, "balance": { "type": [ "number", "null" ], "format": "double", "description": "Remaining balance on the most restrictive budget." }, "budget_id": { "type": [ "string", "null" ], "description": "Budget that triggered the action." }, "currency": { "type": [ "string", "null" ], "description": "Currency of the most restrictive budget." }, "error_code": { "type": [ "string", "null" ], "description": "Stable error code for user-facing budget failures." }, "error_fields": { "type": [ "object", "null" ], "description": "Structured interpolation fields for localized error rendering." }, "message": { "type": [ "string", "null" ], "description": "Human-readable message (set when action != \"continue\")." } } }, "BudgetEventData": { "type": "object", "description": "Data for budget lifecycle events (warning, paused, exhausted, resumed).", "required": [ "budget_id", "balance", "limit", "currency" ], "properties": { "balance": { "type": "number", "format": "double", "description": "Current remaining balance." }, "budget_id": { "type": "string", "description": "Budget that triggered this event." }, "currency": { "type": "string", "description": "Budget currency (e.g. \"usd\", \"tokens\")." }, "limit": { "type": "number", "format": "double", "description": "Budget limit." }, "message": { "type": [ "string", "null" ], "description": "Human-readable message." }, "soft_limit": { "type": [ "number", "null" ], "format": "double", "description": "Soft limit threshold (present for warning/paused events)." } } }, "BudgetPeriod": { "oneOf": [ { "type": "object", "description": "Sliding window of a configurable number of seconds.", "required": [ "seconds", "type" ], "properties": { "seconds": { "type": "integer", "format": "int64", "minimum": 0 }, "type": { "type": "string", "enum": [ "duration" ] } } }, { "type": "object", "description": "Rolling window described as a humanized string (\"5h\", \"24h\", \"30d\").", "required": [ "window", "type" ], "properties": { "type": { "type": "string", "enum": [ "rolling" ] }, "window": { "type": "string" } } }, { "type": "object", "description": "Calendar-aligned (`hour`, `day`, `week`, `month`, `year`).", "required": [ "unit", "type" ], "properties": { "type": { "type": "string", "enum": [ "calendar" ] }, "unit": { "type": "string" } } } ], "description": "Budget period configuration for recurring budgets.\n\nPeriods drive automatic balance reset:\n- `Duration` is a fixed-length sliding window (e.g. last 5 hours, last 30 days)\n measured from `Budget::period_started_at`. When the window elapses the\n balance is reset to `limit` and the window restarts.\n- `Calendar` aligns to a calendar boundary (`hour | day | week | month | year`)\n in UTC. The balance resets when the next boundary is crossed.\n- `Rolling` is preserved for backwards compatibility and parses common\n shorthand (`24h`, `5h`, `7d`, `30d`) into a `Duration`-equivalent reset\n policy." }, "BudgetStatus": { "type": "string", "description": "Budget status.", "enum": [ "active", "paused", "exhausted", "disabled" ] }, "BudgetSubjectType": { "type": "string", "description": "Subject type: what entity this budget constrains.", "enum": [ "session", "agent", "user", "organization", "app", "app_channel", "agent_endpoint" ] }, "BuiltinTool": { "type": "object", "description": "Built-in tool configuration\n\nNote: The `kind` field has been removed. Tools are now identified\nsolely by their `name` field, and execution happens via the ToolRegistry\nwhich looks up tools by name.", "required": [ "name", "description", "parameters" ], "properties": { "category": { "type": [ "string", "null" ], "description": "Category for tool_search namespace grouping (from parent capability)" }, "deferrable": { "$ref": "#/components/schemas/DeferrablePolicy", "description": "Whether this tool's schema can be deferred via tool_search" }, "description": { "type": "string", "description": "Tool description for LLM" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name for UI rendering (e.g., \"Get Current Time\" for `get_current_time`)" }, "full_parameters": { "description": "Original full parameter schema saved by `DeferSchemaHook` before stripping.\nSerialized only when present so durable reason-to-act scheduling can\npreserve deferred schemas for `tool_search` in the act phase." }, "hints": { "$ref": "#/components/schemas/ToolHints", "description": "Semantic hints describing the tool's behavioral properties" }, "name": { "type": "string", "description": "Tool name (used by LLM and for registry lookup)" }, "parameters": { "description": "JSON schema for tool parameters" }, "policy": { "$ref": "#/components/schemas/ToolPolicy", "description": "Tool policy (auto or requires_approval)" } } }, "CancelStatus": { "type": "string", "description": "Status of the cancel operation", "enum": [ "cancelled", "no_op" ] }, "CancelTurnResponse": { "type": "object", "description": "Response from cancel turn endpoint", "required": [ "status", "message" ], "properties": { "message": { "type": "string", "description": "Human-readable message", "example": "Turn cancelled successfully" }, "status": { "$ref": "#/components/schemas/CancelStatus", "description": "Whether the cancellation was performed or was a no-op" } } }, "CapabilityInfo": { "type": "object", "description": "Public capability information (without internal details)\nThis is what gets returned from the API\nNamed CapabilityInfo to distinguish from the Capability trait", "required": [ "id", "name", "description", "status" ], "properties": { "agent_count": { "type": "integer", "format": "int64", "description": "Number of active agents referencing this capability in the org.", "example": 42, "minimum": 0 }, "category": { "type": [ "string", "null" ], "description": "Category for grouping in UI", "example": "filesystem" }, "config_schema": { "type": "object", "description": "JSON Schema for capability-specific per-agent config." }, "config_ui_schema": { "type": "object", "description": "react-jsonschema-form uiSchema hints for rendering config_schema." }, "dependencies": { "type": "array", "items": { "type": "string" }, "description": "IDs of capabilities that this capability depends on.\nWhen this capability is selected, its dependencies are automatically included.", "example": [ "approval" ] }, "description": { "type": "string", "description": "Description of what this capability provides", "example": "Read, write, edit, list, grep, delete, and stat files in the session workspace." }, "docs_slug": { "type": [ "string", "null" ], "description": "Slug under https://dev.everruns.com/capabilities/ when public docs exist.", "example": "session_file_system" }, "features": { "type": "array", "items": { "type": "string" }, "description": "UI feature strings this capability contributes to.\nMultiple capabilities can contribute the same feature.", "example": [ "file_browser" ] }, "harness_count": { "type": "integer", "format": "int64", "description": "Number of active harnesses referencing this capability in the org.", "example": 7, "minimum": 0 }, "icon": { "type": [ "string", "null" ], "description": "Icon name (for UI rendering)", "example": "Folder" }, "id": { "type": "string", "description": "Unique capability identifier", "example": "session_file_system" }, "is_guardrail": { "type": "boolean", "description": "Whether this capability is a guardrail (constrains agent behavior\nrather than granting abilities). Used for UI grouping and filtering.", "example": false }, "is_mcp": { "type": "boolean", "description": "Whether this is an MCP server capability (for UI badge)", "example": false }, "is_skill": { "type": "boolean", "description": "Whether this is an Agent Skill capability (for UI badge)", "example": false }, "localizations": { "type": "object", "description": "Localized display strings keyed by lowercase language tag (e.g. \"uk\").\nThe \"en\" entry carries only `config_description`, since the base\nname/description/config_schema strings are already English.", "additionalProperties": { "$ref": "#/components/schemas/CapabilityLocalizationInfo" }, "propertyNames": { "type": "string" }, "example": { "uk": { "description": "Монтує спільні файли пам'яті в сесії.", "name": "Пам'ять" } } }, "name": { "type": "string", "description": "Display name", "example": "Session File System" }, "risk_level": { "$ref": "#/components/schemas/RiskLevel", "description": "TM-AGENT-005: Risk level. High-risk capabilities require admin approval." }, "status": { "type": "string", "description": "Current status", "example": "active" }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt addition contributed by this capability", "example": "You can read and write files in /workspace via the session_file_system tools." }, "tool_definitions": { "type": "array", "items": { "type": "object" }, "description": "Tool definitions provided by this capability", "example": [ { "description": "Read a file from the session workspace.", "name": "read_file" }, { "description": "Write or overwrite a file in the session workspace.", "name": "write_file" } ] } } }, "CapabilityLocalizationInfo": { "type": "object", "description": "Localized display strings for one locale of a capability.", "properties": { "config_description": { "type": [ "string", "null" ], "description": "One-line summary of what this capability's config controls." }, "config_overlay": { "type": "object", "description": "Overlay merged into `config_schema` before rendering: mirrors the\nschema property tree with `title`/`description`/`enum_labels` leaves." }, "description": { "type": [ "string", "null" ], "description": "Localized description; absent means fall back to `description`." }, "name": { "type": [ "string", "null" ], "description": "Localized display name; absent means fall back to `name`." } } }, "CapabilityUsageData": { "type": "object", "description": "Data for capability.usage events.", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityUsageRecord" } } } }, "CapabilityUsageKind": { "type": "string", "description": "Reporting-only capability usage kinds.", "enum": [ "configured", "resolved", "exposed", "invoked", "effect_ran" ] }, "CapabilityUsageRecord": { "type": "object", "description": "Single capability usage record. This intentionally carries only stable IDs\nand small snapshots; prompts, messages, tool arguments, and results are not\nallowed in reporting facts.", "required": [ "capability_id", "usage_kind" ], "properties": { "capability_id": { "type": "string", "description": "Capability id (prefixed or namespaced) attributing this usage." }, "capability_name": { "type": [ "string", "null" ], "description": "Capability display name for UI. `None` when the capability is unnamed." }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Total wall-clock duration of the usage in milliseconds (duration-style records). `None` for count-style records.", "minimum": 0 }, "tool_name": { "type": [ "string", "null" ], "description": "Concrete tool name when `usage_kind` is `tool_call`. `None` for non-tool usage kinds." }, "usage_count": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of distinct usages recorded in this record (count-style records). `None` for duration-style records.", "minimum": 0 }, "usage_kind": { "$ref": "#/components/schemas/CapabilityUsageKind", "description": "Discriminator for the kind of usage being recorded (e.g. `tool_call`, `subagent_spawn`)." } } }, "ChannelType": { "type": "string", "description": "Supported channel types for app distribution.", "enum": [ "slack", "ag_ui", "schedule", "webhook", "a2a", "fcp", "api_endpoint", "public_chat" ], "example": "webhook" }, "CheckAgentNameResponse": { "type": "object", "description": "Response for agent name availability check.", "required": [ "available" ], "properties": { "available": { "type": "boolean", "description": "Whether the name is available for use." } } }, "CheckCredentialsRequest": { "type": "object", "description": "Request to check a provider credential without storing it.", "required": [ "provider_type" ], "properties": { "api_key": { "type": [ "string", "null" ], "description": "Single-field credential. Mutually exclusive with `credentials`.", "example": "sk-proj-..." }, "base_url": { "type": [ "string", "null" ], "description": "Base URL for the provider's API, when not the driver default.", "example": "https://api.openai.com/v1" }, "credentials": { "type": [ "object", "null" ], "description": "Typed multi-field credential, validated against the driver's schema\nexactly as on create.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "provider_type": { "$ref": "#/components/schemas/DriverId", "description": "The type of LLM provider (e.g., openai, anthropic)." } } }, "CheckNameResponse": { "type": "object", "description": "Response for name availability check.", "required": [ "available" ], "properties": { "available": { "type": "boolean", "description": "Whether the name is available for use." } } }, "CircuitBreakerResponse": { "type": "object", "description": "Circuit breaker response", "required": [ "key", "state", "failure_count", "success_count", "updated_at" ], "properties": { "failure_count": { "type": "integer", "format": "int32", "description": "Count of consecutive failures observed within the current rolling window.", "example": 12, "minimum": 0 }, "half_open_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the breaker is eligible to transition to `half_open` and probe again (RFC 3339).", "example": "2026-05-27T15:30:01Z" }, "key": { "type": "string", "description": "Stable key identifying the dependency the breaker guards (e.g. provider URL or activity type).", "example": "anthropic_api" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent failure recorded against this breaker (RFC 3339).", "example": "2026-05-27T15:25:00Z" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the breaker last transitioned to `open` (RFC 3339).", "example": "2026-05-27T15:25:01Z" }, "state": { "type": "string", "description": "Current breaker state (`closed`, `open`, or `half_open`).", "example": "open" }, "success_count": { "type": "integer", "format": "int32", "description": "Count of consecutive successes observed within the current rolling window.", "example": 0, "minimum": 0 }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this breaker state was last updated (RFC 3339).", "example": "2026-05-27T15:25:01Z" } } }, "CircuitBreakersListResponse": { "type": "object", "description": "Circuit breakers list response", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CircuitBreakerResponse" }, "description": "Page of items returned by this query." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages.", "minimum": 0 } } }, "ClientSideTool": { "type": "object", "description": "Client-side tool - executed by the client, not the server\nThe server pauses execution and waits for the client to submit results.", "required": [ "name", "description", "parameters" ], "properties": { "category": { "type": [ "string", "null" ], "description": "Category for tool_search namespace grouping (from parent capability)" }, "deferrable": { "$ref": "#/components/schemas/DeferrablePolicy", "description": "Whether this tool's schema can be deferred via tool_search" }, "description": { "type": "string", "description": "Tool description for LLM" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name for UI rendering" }, "full_parameters": { "description": "Original full parameter schema saved by `DeferSchemaHook` before stripping.\nSerialized only when present so durable reason-to-act scheduling can\npreserve deferred schemas for `tool_search` in the act phase." }, "hints": { "$ref": "#/components/schemas/ToolHints", "description": "Semantic hints describing the tool's behavioral properties" }, "name": { "type": "string", "description": "Tool name (used by LLM and for correlation)" }, "parameters": { "description": "JSON schema for tool parameters" } } }, "ClientToolResult": { "type": "object", "description": "A single tool result from the client", "required": [ "tool_call_id" ], "properties": { "error": { "type": [ "string", "null" ], "description": "Error message if the tool failed", "example": "Refund failed: order is outside refund window" }, "result": { "description": "Result value (any JSON — object, array, string, number, etc.). Null if the tool failed.\nExample: `{\"url\": \"https://example.com/orders/42\"}`." }, "tool_call_id": { "type": "string", "description": "Tool call ID (correlates with the tool call from tool.call_requested event)", "example": "toolu_01933b5a00007000800000000000001" } } }, "CommitRequest": { "type": "object", "description": "Request to create a commit", "required": [ "message" ], "properties": { "author_email": { "type": [ "string", "null" ], "description": "Author email (defaults to \"agent@everruns.local\")", "example": "support-agent@example.com" }, "author_name": { "type": [ "string", "null" ], "description": "Author name (defaults to \"Agent\")", "example": "Support Agent" }, "branch": { "type": [ "string", "null" ], "description": "Branch name (defaults to \"refs/heads/main\"); short names like \"main\" are normalized", "example": "main" }, "message": { "type": "string", "description": "Commit message", "example": "feat: draft migration plan" } } }, "CommitResult": { "type": "object", "description": "Result of a commit operation", "required": [ "oid", "tree_oid", "objects_created" ], "properties": { "objects_created": { "type": "integer", "minimum": 0 }, "oid": { "type": "string" }, "tree_oid": { "type": "string" } } }, "CompactionFailStage": { "type": "string", "description": "Which stage of a compaction attempt failed.", "enum": [ "native_compaction", "checkpoint_install", "summarization" ] }, "CompactionReason": { "type": "string", "description": "Reason why compaction was triggered.", "enum": [ "proactive_budget", "request_too_large", "manual" ] }, "CompactionSkipReason": { "type": "string", "description": "Why a pressured compaction evaluation did not install compacted context.", "enum": [ "strategy_excludes_native", "driver_unsupported", "checkpoint_store_unavailable", "cooldown_active", "native_returned_none", "no_material_reduction", "guard_rejected" ] }, "CompactionStepData": { "type": "object", "description": "A single step in a compaction cascade.", "required": [ "strategy", "messages_after", "duration_ms" ], "properties": { "duration_ms": { "type": "integer", "format": "int64", "description": "Duration of this step in milliseconds.", "minimum": 0 }, "messages_after": { "type": "integer", "description": "Number of messages after this step.", "minimum": 0 }, "strategy": { "type": "string", "description": "Strategy used in this step." } } }, "CompactionTrigger": { "type": "string", "description": "What triggered a compaction lifecycle: the context-window budget or cost pressure.", "enum": [ "context_budget", "cost_pressure" ] }, "Connection": { "type": "object", "description": "Connection info returned in API responses (never includes token)", "required": [ "provider", "connection_type", "connected_at" ], "properties": { "connected_at": { "type": "string", "format": "date-time" }, "connection_type": { "type": "string" }, "provider": { "type": "string" }, "provider_username": { "type": [ "string", "null" ] }, "scopes": { "type": [ "string", "null" ] } } }, "ConsentAction": { "type": "string", "description": "What the user decided about opening the URL.", "enum": [ "accept", "decline" ] }, "ContentPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextContentPart", "description": "Text content" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } } ], "description": "Text content" }, { "allOf": [ { "$ref": "#/components/schemas/ImageContentPart", "description": "Image content (base64 or URL)" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image" ] } } } ], "description": "Image content (base64 or URL)" }, { "allOf": [ { "$ref": "#/components/schemas/ImageFileContentPart", "description": "Image file content (reference to uploaded image by ID)" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_file" ] } } } ], "description": "Image file content (reference to uploaded image by ID)" }, { "allOf": [ { "$ref": "#/components/schemas/FileContentPart", "description": "File content (reference to uploaded file, e.g. PDF, by ID)" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file" ] } } } ], "description": "File content (reference to uploaded file, e.g. PDF, by ID)" }, { "allOf": [ { "$ref": "#/components/schemas/ToolCallContentPart", "description": "Tool call content (assistant requesting tool execution)" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool_call" ] } } } ], "description": "Tool call content (assistant requesting tool execution)" }, { "allOf": [ { "$ref": "#/components/schemas/ToolResultContentPart", "description": "Tool result content (result of tool execution)" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool_result" ] } } } ], "description": "Tool result content (result of tool execution)" }, { "allOf": [ { "$ref": "#/components/schemas/ReasoningContentPart", "description": "Provider reasoning artifact, ordered against the text and tool calls it\nwas interleaved with." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "reasoning" ] } } } ], "description": "Provider reasoning artifact, ordered against the text and tool calls it\nwas interleaved with." } ], "description": "A part of message content - can be text, image, image_file, tool_call, or tool_result\n\nThis is the canonical content part type used across the system.\nAPI layer enables the \"openapi\" feature to add ToSchema derive." }, "ContextCompactedData": { "type": "object", "description": "Data for context.compacted event (compaction completed).", "required": [ "strategy_used", "messages_before", "messages_after", "duration_ms" ], "properties": { "budget_remaining_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens of headroom remaining when the install completed, when measurable.", "example": 8192, "minimum": 0 }, "bytes_after": { "type": [ "integer", "null" ], "format": "int64", "description": "Serialized compact output bytes, when measurable.", "minimum": 0 }, "bytes_before": { "type": [ "integer", "null" ], "format": "int64", "description": "Serialized request-context bytes before compaction, when measurable.", "minimum": 0 }, "cache_creation_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Cache-creation tokens written after compaction, when reported.", "example": 1024, "minimum": 0 }, "cache_read_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Cached input tokens read after compaction, when reported.", "example": 90210, "minimum": 0 }, "checkpoint_id": { "type": [ "string", "null" ], "description": "Durable checkpoint installed by this compaction, when applicable.", "example": "01934c2f-9f2e-7c1b-8d3e-4f5a6b7c8d9e" }, "driver": { "type": [ "string", "null" ], "description": "Local driver identifier, when known.", "example": "openai-chat" }, "duration_ms": { "type": "integer", "format": "int64", "description": "Total duration of all compaction steps in milliseconds.", "minimum": 0 }, "messages_after": { "type": "integer", "description": "Number of messages after compaction.", "minimum": 0 }, "messages_before": { "type": "integer", "description": "Number of messages before compaction.", "example": 120, "minimum": 0 }, "model": { "type": "string", "description": "Model that performed the compaction.", "example": "gpt-5-mini" }, "provider": { "type": [ "string", "null" ], "description": "Provider backend (e.g. \"openai\"), when known.", "example": "openai" }, "source_sequence": { "type": [ "integer", "null" ], "format": "int64", "description": "Source message sequence the compaction ran at, when known.", "example": 481 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/CompactionStepData" }, "description": "Individual steps in the cascade." }, "strategy_used": { "type": "string", "description": "Combined strategy description (e.g., \"observation_masking+native\")." }, "tokens_after": { "type": [ "integer", "null" ], "format": "int64", "description": "Provider-reported output tokens after compaction, when available.", "minimum": 0 }, "tokens_before": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated or provider-reported input tokens before compaction.", "example": 184320, "minimum": 0 }, "trigger": { "$ref": "#/components/schemas/CompactionTrigger", "description": "What triggered this compaction: context-window budget or cost pressure." } } }, "ContextCompactingData": { "type": "object", "description": "Data for context.compacting event (compaction starting).", "required": [ "reason", "strategy", "messages_before" ], "properties": { "budget_remaining_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens of headroom remaining when the attempt started, when measurable.", "example": 8192, "minimum": 0 }, "bytes_before": { "type": [ "integer", "null" ], "format": "int64", "description": "Serialized request-context bytes before compaction, when measurable.", "minimum": 0 }, "cache_creation_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Cache-creation tokens written before compaction, when reported.", "example": 1024, "minimum": 0 }, "cache_read_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Cached input tokens read before compaction, when reported.", "example": 90210, "minimum": 0 }, "driver": { "type": [ "string", "null" ], "description": "Local driver identifier, when known.", "example": "openai-chat" }, "messages_before": { "type": "integer", "description": "Number of messages before compaction.", "example": 120, "minimum": 0 }, "model": { "type": "string", "description": "Model performing the compaction.", "example": "gpt-5-mini" }, "provider": { "type": [ "string", "null" ], "description": "Provider backend (e.g. \"openai\"), when known.", "example": "openai" }, "reason": { "$ref": "#/components/schemas/CompactionReason", "description": "Why compaction was triggered." }, "source_sequence": { "type": [ "integer", "null" ], "format": "int64", "description": "Source message sequence the attempt ran at, when known.", "example": 481 }, "strategy": { "type": "string", "description": "Strategy requested (may differ from strategy_used in the completed event).", "example": "summary_then_trim" }, "tokens_before": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated or provider-reported input tokens before compaction.", "example": 184320, "minimum": 0 }, "trigger": { "$ref": "#/components/schemas/CompactionTrigger", "description": "What triggered this attempt: context-window budget or cost pressure." } } }, "ContextCompactionFailedData": { "type": "object", "description": "Data for context.compaction.failed: an attempt errored before installing.\n\nTerminal event for an emitted context.compacting attempt that did not\ninstall. The envelope timestamp records when the failure surfaced.", "required": [ "reason", "trigger", "stage", "error", "strategy", "model", "tokens_before", "messages_before" ], "properties": { "budget_remaining_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens of headroom remaining, when measurable.", "example": 8192, "minimum": 0 }, "checkpoint_id": { "type": [ "string", "null" ], "description": "Durable checkpoint being installed when the failure hit, if any.", "example": "01934c2f-9f2e-7c1b-8d3e-4f5a6b7c8d9e" }, "driver": { "type": [ "string", "null" ], "description": "Local driver identifier, when known.", "example": "openai-chat" }, "error": { "type": "string", "description": "Human-readable failure.", "example": "summarizer request failed: upstream timed out" }, "messages_before": { "type": "integer", "description": "Number of messages before the attempt.", "example": 120, "minimum": 0 }, "model": { "type": "string", "description": "Model the attempt ran under.", "example": "gpt-5-mini" }, "provider": { "type": [ "string", "null" ], "description": "Provider backend (e.g. \"openai\"), when known.", "example": "openai" }, "reason": { "$ref": "#/components/schemas/CompactionReason", "description": "Why compaction was attempted." }, "source_sequence": { "type": [ "integer", "null" ], "format": "int64", "description": "Source message sequence the attempt ran at, when known.", "example": 481 }, "stage": { "$ref": "#/components/schemas/CompactionFailStage", "description": "Which stage failed." }, "strategy": { "type": "string", "description": "Strategy requested.", "example": "summary_then_trim" }, "tokens_before": { "type": "integer", "format": "int64", "description": "Estimated or provider-reported input tokens before the attempt.", "example": 184320, "minimum": 0 }, "trigger": { "$ref": "#/components/schemas/CompactionTrigger", "description": "Whether window/budget or cost pressure triggered the attempt." } } }, "ContextCompactionSkippedData": { "type": "object", "description": "Data for context.compaction.skipped: pressure observed, nothing installed.\n\nEmitted when context-budget or cost pressure is present but the evaluation\ndoes not install compacted context. The envelope timestamp records when the\ndecision was made; every pressured evaluation closes with exactly one of\nskipped, installed (context.compacted), or failed.", "required": [ "reason", "trigger", "skip_reason", "strategy", "model", "tokens_observed", "messages_observed" ], "properties": { "budget_remaining_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Tokens of headroom remaining, when measurable.", "example": 8192, "minimum": 0 }, "driver": { "type": [ "string", "null" ], "description": "Local driver identifier, when known.", "example": "openai-chat" }, "messages_observed": { "type": "integer", "description": "Number of messages observed.", "example": 120, "minimum": 0 }, "model": { "type": "string", "description": "Model the evaluation ran under.", "example": "gpt-5-mini" }, "provider": { "type": [ "string", "null" ], "description": "Provider backend (e.g. \"openai\"), when known.", "example": "openai" }, "reason": { "$ref": "#/components/schemas/CompactionReason", "description": "Why compaction was evaluated." }, "skip_reason": { "$ref": "#/components/schemas/CompactionSkipReason", "description": "Why nothing was installed." }, "source_sequence": { "type": [ "integer", "null" ], "format": "int64", "description": "Source message sequence the evaluation ran at, when known.", "example": 481 }, "strategy": { "type": "string", "description": "Strategy requested.", "example": "summary_then_trim" }, "tokens_observed": { "type": "integer", "format": "int64", "description": "Estimated input tokens observed at evaluation time.", "example": 184320, "minimum": 0 }, "trigger": { "$ref": "#/components/schemas/CompactionTrigger", "description": "Whether window/budget or cost pressure triggered the evaluation." } } }, "ContextReportContribution": { "type": "object", "description": "Single-source token contribution within a `ContextReportSection` — the\nper-tool / per-capability / per-message attribution that lets operators\nsee which source is eating the context window.", "required": [ "section_key", "source_id", "label", "tokens" ], "properties": { "label": { "type": "string", "description": "Human-readable label suitable for UI display." }, "section_key": { "type": "string", "description": "Section this contribution rolls up into; matches `ContextReportSection.key`." }, "source_id": { "type": "string", "description": "Stable id of the contributing source (capability id, tool name, message id, etc.)." }, "tokens": { "type": "integer", "format": "int32", "description": "Tokens this single source contributes to the assembled context.", "minimum": 0 } } }, "ContextReportSection": { "type": "object", "description": "One logical section of the assembled LLM context (system prompt, tool\ndefinitions, message history, etc.) with its rolled-up token budget.", "required": [ "key", "label", "tokens", "items" ], "properties": { "items": { "type": "integer", "format": "int32", "description": "Number of items this section comprises (messages, tool defs, etc.).", "minimum": 0 }, "key": { "type": "string", "description": "Stable section key (e.g. `system_prompt`, `tools`, `history`). Used as a join key for contributions." }, "label": { "type": "string", "description": "Human-readable section label suitable for UI display." }, "tokens": { "type": "integer", "format": "int32", "description": "Total tokens this section contributes to the assembled context.", "minimum": 0 } } }, "Controls": { "type": "object", "description": "Runtime controls for message processing", "properties": { "error_disclosure": { "type": [ "string", "null" ], "description": "Error disclosure override for this turn: \"generic\", \"standard\", or\n\"detailed\". Clamped to at most the mode allowed by the agent's\n`error_disclosure` capability (capability absent => \"standard\"), so a\nclient can narrow but never widen disclosure." }, "hints": { "type": [ "object", "null" ], "description": "Generic client hints — arbitrary key-value pairs declared by the client.\nSession-level defaults are set at session creation; per-message values\noverride session hints key-by-key (shallow merge).\n\nExamples: `{\"setup_connection\": true, \"rich_media\": true}`" }, "locale": { "type": [ "string", "null" ], "description": "Locale override for this message turn (BCP 47, e.g. `uk-UA`).\nOverrides the session locale for backend-authored strings and prompts." }, "model_id": { "type": [ "string", "null" ], "description": "Model ID to use for this message (format: model_{32-hex}).\nOverrides session and agent model settings.", "example": "model_01933b5a00007000800000000000001" }, "reasoning": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningConfig", "description": "Reasoning configuration" } ] }, "speed": { "type": [ "string", "null" ], "description": "Speed (service tier) for this message turn: \"flex\", \"default\", or\n\"priority\". Only sent to providers whose model profile advertises a\nspeed config (OpenAI `service_tier`)." }, "verbosity": { "type": [ "string", "null" ], "description": "Verbosity for this message turn: \"low\", \"medium\", or \"high\". Only sent\nto providers whose model profile advertises a verbosity config (OpenAI\n`verbosity`)." } } }, "ConversationStarter": { "type": "object", "description": "A conversation starter shown on a fresh Platform Chat thread.\nSelecting one inserts its text into the composer. `icon` reuses the\nharness icon name set (`HarnessIcon`); unknown names fall back to the\ndefault glyph.", "required": [ "text" ], "properties": { "icon": { "type": [ "string", "null" ], "description": "Optional icon name from the harness icon set.", "example": "zap" }, "text": { "type": "string", "description": "Prompt text inserted into the composer when selected.", "example": "Triage the newest P1" } } }, "CopyFileRequest": { "type": "object", "description": "Request to copy a file", "required": [ "src_path", "dst_path" ], "properties": { "dst_path": { "type": "string", "description": "Destination path (relative to the workspace filesystem root).", "example": "docs/runbooks/refund-30-days.md" }, "src_path": { "type": "string", "description": "Source path (relative to the workspace filesystem root).", "example": "templates/runbook.md" } } }, "CostTier": { "type": "object", "description": "A pricing tier that activates above a context token threshold.\nFor example, OpenAI charges higher rates for prompts exceeding 200K tokens.", "required": [ "above_tokens", "input", "output" ], "properties": { "above_tokens": { "type": "integer", "format": "int32", "description": "Context token threshold above which this tier applies" }, "cache_read": { "type": [ "number", "null" ], "format": "double", "description": "Cached read cost per million tokens (USD) for this tier, if supported" }, "cache_write": { "type": [ "number", "null" ], "format": "double", "description": "Cache write cost per million tokens (USD); absent falls back to input." }, "input": { "type": "number", "format": "double", "description": "Input cost per million tokens (USD) for this tier" }, "output": { "type": "number", "format": "double", "description": "Output cost per million tokens (USD) for this tier" } } }, "CreateAgentCredentialBinding": { "type": "object", "description": "Declare a credential requirement for an agent's attached MCP tool.", "required": [ "mcp_server_name", "tool_name", "parameter_name", "label" ], "properties": { "agent_id": { "type": "string", "description": "Agent ID, populated from the request path by the HTTP API.", "example": "agent_01933b5a000070008000000000000001" }, "description": { "type": [ "string", "null" ], "description": "Optional explanation of how the credential will be used.", "example": "Delivers scheduled status notifications" }, "label": { "type": "string", "description": "Human-readable label shown in the secure setup UI.", "example": "Visti channel key" }, "mcp_server_name": { "type": "string", "description": "Name of an MCP server attached to the agent.", "example": "visti" }, "parameter_name": { "type": "string", "description": "Top-level tool argument to inject outside model context.", "example": "channel_key" }, "tool_name": { "type": "string", "description": "MCP tool whose outbound call requires the credential.", "example": "visti_send" } } }, "CreateAgentEndpointRequest": { "type": "object", "description": "Request to create an ingress endpoint owned by an Agent.", "required": [ "channel_type" ], "properties": { "channel_config": { "description": "Transport-specific endpoint configuration." }, "channel_type": { "$ref": "#/components/schemas/ChannelType", "description": "Transport used by the endpoint." }, "enabled": { "type": "boolean", "description": "Whether the endpoint can accept ingress traffic." } } }, "CreateAgentRequest": { "type": "object", "description": "Request to create a new agent", "required": [ "name", "system_prompt" ], "properties": { "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities to enable for this agent with per-agent configuration.\nEach capability has a `ref` (capability ID) and optional `config`.", "example": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "web_fetch" } ] }, "default_model_id": { "type": [ "string", "null" ], "description": "The ID of the default LLM model to use for this agent.\nIf not specified, the system default model will be used.", "example": "model_01933b5a00007000800000000000001" }, "description": { "type": [ "string", "null" ], "description": "A human-readable description of what the agent does.", "example": "Handles customer inquiries and support tickets" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI.\nFalls back to `name` when absent.", "example": "Customer Support Agent" }, "harness_id": { "type": [ "string", "null" ], "description": "Harness ID used as this agent's base execution environment. If omitted,\nthe org's built-in `generic` harness is used.", "example": "harness_01933b5a00007000800000000000001" }, "harness_name": { "type": [ "string", "null" ], "description": "Addressable harness name. Alternative to `harness_id`.", "example": "generic" }, "id": { "type": [ "string", "null" ], "description": "Client-supplied agent ID (format: agent_{32-hex}).\nIf not provided, one is auto-generated.", "example": "agent_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this agent.", "example": [ { "content": "Always respond in formal English.\n", "path": "INSTRUCTIONS.md" } ] }, "intro_markdown": { "type": [ "string", "null" ], "description": "Markdown intro shown as an intro box on a fresh Platform Chat thread.\nImages are allowed. Wins over the harness intro. Hidden once the user\ninputs.", "example": "Hey, I'm Ava. Ask me anything about your account." }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this agent.", "example": 20, "minimum": 0 }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this agent." }, "name": { "type": "string", "description": "Name, unique per org. Lowercase alphanumeric and hyphens.\nFormat: lowercase alphanumeric and hyphens (e.g. \"customer-support\").", "example": "customer-support" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs this agent's sessions can reach.\nIf set, merged with harness and session layers (allowed: intersect, blocked: union).\nExample shape is defined on `NetworkAccessList`." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598). `true` signals\nthe provider that parallel tool calls are wanted; `false` requests at\nmost one tool call per turn and forces serial execution. Omit to use the\nprovider default.", "example": true }, "short_description": { "type": [ "string", "null" ], "description": "One-line description in simplified Markdown, shown below the chat title\nonce the intro is hidden. Wins over the harness value.", "example": "Answers account questions in seconds." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. Win over the\nharness starters when non-empty. `icon` reuses the harness icon set." }, "system_prompt": { "type": "string", "description": "The system prompt that defines the agent's behavior and capabilities.\nThis is sent as the first message in every conversation.", "example": "You are a helpful customer support agent. Be polite and professional." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering agents.", "example": [ "support", "customer-facing" ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools for this agent.\nThese tools are sent to the LLM but executed by the client, not the server.", "example": [ { "description": "Open URL in the user's browser", "name": "open_url", "parameters": { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "type": "client_side" } ] } } }, "CreateAgentTriggerRequest": { "type": "object", "description": "Request to create a trigger on an agent.", "required": [ "message" ], "properties": { "auth": { "description": "Shared endpoint auth is not supported by webhook triggers." }, "cron_expression": { "type": [ "string", "null" ], "description": "Cron expression that drives the durable schedule. Accepts 5-field\n(min hour day month weekday) or 7-field (sec … year) form.", "example": "0 9 * * *" }, "enabled": { "type": "boolean", "description": "Whether the trigger is active on creation (default `true`)." }, "message": { "type": "string", "description": "Message content or `{{template}}` sent when the trigger fires.", "example": "Run the daily digest" }, "rate_limit_per_minute": { "type": [ "integer", "null" ], "format": "int32", "description": "Optional per-ingress, per-IP webhook request limit.", "minimum": 0 }, "session_mode": { "$ref": "#/components/schemas/SessionBinding", "description": "Whether invocations reuse a stable session or create a new one." }, "timezone": { "type": "string", "description": "IANA timezone identifier for cron evaluation (default `UTC`).", "example": "UTC" }, "token": { "type": [ "string", "null" ], "description": "Shared secret for webhook triggers." }, "trigger_type": { "$ref": "#/components/schemas/AgentTriggerType", "description": "Trigger kind. Omitted values retain the schedule API default." } } }, "CreateAgentVersionRequest": { "type": "object", "description": "Request body for the `create_agent_version` operation.", "properties": { "change_kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentVersionChangeKind", "description": "Reason this version was created. See `AgentVersionChangeKind` for the allowed values.\nDefaults to `manual` when omitted." } ] }, "summary": { "type": [ "string", "null" ], "description": "Free-text summary of what changed in this version. Shown in the version timeline.", "example": "Tightened the refund-window check and added a regression test." } } }, "CreateBranchRequest": { "type": "object", "description": "Request to create a branch", "required": [ "name", "commit_oid" ], "properties": { "commit_oid": { "type": "string", "description": "Commit OID (hex) to point to", "example": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678" }, "name": { "type": "string", "description": "Branch name (e.g., \"feature-xyz\")", "example": "feature/refund-flow" } } }, "CreateBudgetRequest": { "type": "object", "description": "Request body for creating a spending budget.", "required": [ "subject_type", "subject_id", "currency", "limit" ], "properties": { "currency": { "type": "string", "description": "Unit in which usage and the limit are measured.", "example": "usd" }, "limit": { "type": "number", "format": "double", "description": "Hard spending ceiling for the budget.", "example": 100.0 }, "metadata": { "description": "Free-form metadata attached to this resource." }, "period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BudgetPeriod", "description": "Optional recurring reset period for the budget balance." } ] }, "soft_limit": { "type": [ "number", "null" ], "format": "double", "description": "Optional threshold that triggers a warning or pause before exhaustion.", "example": 20.0 }, "subject_id": { "type": "string", "description": "Public identifier of the constrained resource.", "example": "agent_01933b5a00007000800000000000001" }, "subject_type": { "type": "string", "description": "Kind of resource constrained by the budget.", "example": "agent" } } }, "CreateDatabaseRequest": { "type": "object", "description": "Request body for creating a database.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Database name (alphanumeric + underscores, max 64 chars).", "example": "refund_history" } } }, "CreateDeclarativeCapabilityRequest": { "type": "object", "description": "Request body for the `create_declarative_capability` operation.", "required": [ "definition" ], "properties": { "definition": { "type": "object", "description": "Definition for the new declarative capability. `name` must be unique per org and becomes the canonical `declarative:` capability ref." } } }, "CreateFileRequest": { "type": "object", "description": "Request to create a file", "properties": { "content": { "type": [ "string", "null" ], "description": "File content (text or base64-encoded). Must match `encoding`.", "example": "# Project notes\n\nDraft outline of the migration plan.\n" }, "encoding": { "type": [ "string", "null" ], "description": "Content encoding: \"text\" or \"base64\". Defaults to text.", "example": "text" }, "is_directory": { "type": [ "boolean", "null" ], "description": "Whether to create a directory instead of a file (ignores `content`/`encoding`).", "example": false }, "is_readonly": { "type": [ "boolean", "null" ], "description": "Whether file is read-only", "example": false } } }, "CreateHarnessRequest": { "type": "object", "description": "Request to create a new harness", "required": [ "name" ], "properties": { "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities to enable with per-harness configuration.", "example": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "web_fetch" } ] }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model ID for this harness. Lowest priority in model chain.", "example": "model_01933b5a00007000800000000000001" }, "description": { "type": [ "string", "null" ], "description": "Description of what the harness does.", "example": "Research harness with planning and web capabilities" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI.", "example": "Deep Research" }, "embedder_metadata": { "type": "object", "description": "Arbitrary key-value metadata injected into LLM requests for observability.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this harness." }, "intro_markdown": { "type": [ "string", "null" ], "description": "Markdown intro shown as an intro box on a fresh Platform Chat thread.\nImages are allowed. The agent intro wins. Hidden once the user inputs.", "example": "I triage incidents, dig through logs, and draft the update." }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this harness." }, "name": { "type": "string", "description": "Name, unique per org. Lowercase alphanumeric and hyphens.", "example": "deep-research" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs sessions can reach." } ] }, "parent_harness_id": { "type": [ "string", "null" ], "description": "Optional parent harness to inherit from.", "example": "harness_01933b5a000070008000000000000602" }, "short_description": { "type": [ "string", "null" ], "description": "One-line description in simplified Markdown, shown below the chat title\nonce the intro is hidden. The agent value wins.", "example": "Triage incidents, dig through logs, draft the update." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. Selecting one\ninserts its text into the composer. The agent starters win when\nnon-empty. `icon` reuses the harness icon name set." }, "system_prompt": { "type": [ "string", "null" ], "description": "Base system prompt defining the harness's behavior. Optional: omit (or\nsend an empty string) to contribute no base prompt, in which case the\neffective prompt comes from the parent harness, agent, session, and\ncapability layers.", "example": "You are a research assistant with deep analytical capabilities." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing harnesses.", "example": [ "research", "planning" ] } } }, "CreateKnowledgeBaseRequest": { "type": "object", "description": "Request body for the `create_knowledge_base` operation.", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Runbooks for the support team" }, "embedding_model_id": { "type": [ "string", "null" ], "description": "Optional embedding model for hybrid retrieval. Omit or null for keyword search only." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "support-runbooks" } } }, "CreateKnowledgeEntryRequest": { "type": "object", "description": "Request body for the `create_knowledge_entry` operation.", "required": [ "title", "body" ], "properties": { "body": { "type": "string", "description": "Entry body. Markdown is rendered when displayed.", "example": "Use the `/v1/payments/{id}/refund` endpoint with `reason: \"past_window\"`. Only the on-call billing engineer can authorize this." }, "kind": { "type": [ "string", "null" ], "description": "Discriminator selecting the variant of this resource. One of `note`,\n`table`, `business`, `query`, `runbook`.", "example": "runbook" }, "resource": { "type": [ "string", "null" ], "description": "Optional OKF resource URI identifying the underlying asset.", "example": "https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Free-form tags attached to this resource.", "example": [ "billing", "refunds" ] }, "title": { "type": "string", "description": "Human-readable title. Safe to render in user-facing messages.", "example": "Refund a payment past 30 days" } } }, "CreateKnowledgeIndexRequest": { "type": "object", "description": "Request body for the `create_knowledge_index` operation.", "required": [ "name", "embedding_model_id" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Synced product documentation" }, "embedding_model_id": { "type": "string", "description": "Embedding model used to embed chunks. Required." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "product-docs" }, "source_config": { "description": "Non-secret source coordinates. GitHub repositories accept `owner/repo`\nor canonical `https://github.com/owner/repo[.git]` URLs. Never include credentials." }, "source_type": { "type": [ "string", "null" ], "description": "External source type. One of `github`, `git`. Defaults to `github`.", "example": "github" } } }, "CreateMcpServerRequest": { "type": "object", "description": "Request to create a new MCP server", "required": [ "name", "url" ], "properties": { "api_key": { "type": [ "string", "null" ], "description": "API key for authentication (optional). Sent with each request; never echoed in responses.", "example": "mcp-api-key-redacted-1234567890abcdef" }, "auth_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpServerAuthMode", "description": "Authentication mode. Defaults to `api_key` when `api_key` is provided, otherwise `none`.\nExample shape is defined on `McpServerAuthMode`." } ] }, "description": { "type": [ "string", "null" ], "description": "A human-readable description of what the MCP server provides.", "example": "Atlassian MCP Server for Jira and Confluence" }, "headers": { "type": [ "object", "null" ], "description": "Additional HTTP headers for authentication.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": { "X-Atlassian-Cloud-Id": "00000000-0000-0000-0000-000000000000" } }, "name": { "type": "string", "description": "The name of the MCP server. Must be unique.", "example": "atlassian-mcp-server" }, "protocol_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpProtocolMode", "description": "Protocol-era policy. Defaults to `auto` (negotiates every protocol era)." } ] }, "transport_type": { "$ref": "#/components/schemas/McpServerTransportType", "description": "Transport type. Currently only \"http\" is supported.\nExample shape is defined on `McpServerTransportType`." }, "url": { "type": "string", "description": "The URL of the MCP server endpoint.", "example": "https://mcp.atlassian.com/v1/mcp" } } }, "CreateMemoryFileRequest": { "type": "object", "properties": { "content": { "type": [ "string", "null" ], "description": "File content (text or base64). Default empty." }, "encoding": { "type": [ "string", "null" ], "description": "\"text\" or \"base64\". Defaults to \"text\"." }, "is_directory": { "type": [ "boolean", "null" ], "description": "If true, create a directory instead of a file." } } }, "CreateMemoryRequest": { "type": "object", "description": "Request body for the `create_memory` operation.", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Living design documents synced from GitHub" }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "design-docs" }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateMemorySourceRequest", "description": "Source configuration. Example shape is defined on `CreateMemorySourceRequest`." } ] } } }, "CreateMemorySourceRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/GitHubMemorySourceRequest" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "github" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/GitMemorySourceRequest" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "git" ] } } } ] } ], "description": "Request body for the `create_memory_source` operation.", "example": { "branch": "main", "repository": "acme/design-docs", "root_folder": "docs/", "type": "github" } }, "CreateMessageRequest": { "type": "object", "description": "Request to create a message", "required": [ "message" ], "properties": { "addressed_participant_id": { "type": [ "string", "null" ], "description": "Optional active agent participant to address for this turn. When omitted,\nthe session host remains the responder.", "example": "part_01933b5a00007000800000000000001" }, "controls": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Controls", "description": "Runtime controls (model, reasoning, etc.)" } ] }, "external_actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalActor", "description": "External actor identity (for messages from external channels like Slack)" } ] }, "message": { "$ref": "#/components/schemas/InputMessage", "description": "The message to create. Example shape is defined on `InputMessage`." }, "metadata": { "type": [ "object", "null" ], "description": "Request-level metadata. Arbitrary key/value pairs persisted with the message\nfor downstream filtering and analytics. Not interpreted by the agent.", "additionalProperties": {}, "propertyNames": { "type": "string" }, "example": { "source": "slack", "thread_ts": "1715000000.123456" } }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tags for the message. Free-form labels used for grouping and filtering.", "example": [ "bug-report", "from-slack" ] } } }, "CreateMessageResult": { "oneOf": [ { "$ref": "#/components/schemas/Message" }, { "$ref": "#/components/schemas/TurnWaitResponse" } ] }, "CreateModelRequest": { "type": "object", "description": "Request to create a new LLM model for a provider", "required": [ "model_id", "display_name" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "List of capabilities this model supports (e.g., \"chat\", \"vision\", \"tools\").", "example": [ "chat", "vision", "tools" ] }, "display_name": { "type": "string", "description": "Human-readable display name for the model.", "example": "GPT-4o" }, "enabled": { "type": "boolean", "description": "Whether this model should be enabled (visible in UI model pickers).", "example": false }, "is_favorite": { "type": "boolean", "description": "Whether this model should be marked as a favorite for quick access.", "example": false }, "model_id": { "type": "string", "description": "The model identifier used by the provider's API (e.g., \"gpt-5.6-sol\", \"claude-opus-5\").", "example": "gpt-5.2" } } }, "CreateOrganizationRequest": { "type": "object", "description": "Request to create a new organization", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The display name of the organization.", "example": "Acme Corp" } } }, "CreatePaymentAccountRequest": { "type": "object", "description": "Request body for the `create_payment_account` operation.", "required": [ "owner_type", "owner_id", "rail", "label" ], "properties": { "label": { "type": "string", "description": "Human-readable label. Safe to render in user-facing messages.", "example": "Refund agent · USDC on Base" }, "metadata": { "description": "Free-form metadata attached to this account (caller-defined; opaque to the platform).\nExample: `{\"team\": \"support\", \"cost_center\": \"ops\"}`." }, "owner_id": { "type": "string", "description": "Prefixed identifier of the owning principal. Must use the prefix that matches `owner_type`\n(see above). Example below pairs with `owner_type = \"agent_identity\"`.", "example": "identity_01933b5a00007000800000000000001" }, "owner_type": { "type": "string", "description": "Principal class that owns the account. One of: `user`, `agent_identity`, `organization`.\nThe prefix on `owner_id` must match this: `user` → `user_…`, `agent_identity` → `identity_…`,\n`organization` → `org_…`.", "example": "agent_identity" }, "private_key": { "type": [ "string", "null" ], "description": "Private key material for the rail. Stored encrypted; never returned in responses.\nExample shown as an obvious placeholder — supply a real 32-byte hex value at create time.", "example": "0x" }, "public_address": { "type": [ "string", "null" ], "description": "Public address on the rail (chain address, account number, etc.). Optional; can be filled in later.", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "rail": { "type": "string", "description": "Settlement rail this account operates on. One of: `mpp_tempo`, `x402_base`.", "example": "x402_base" } } }, "CreatePaymentPolicyRequest": { "type": "object", "description": "Request body for the `create_payment_policy` operation.", "required": [ "payment_account_id", "subject_type", "subject_id" ], "properties": { "allowed_capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability IDs this policy permits paid calls for. Empty list means no capability gating.", "example": [ "weather.lookup", "shipping.quote" ] }, "allowed_hosts": { "type": "array", "items": { "type": "string" }, "description": "HTTP host allowlist for paid outbound calls. Empty list means no host gating.", "example": [ "api.shippo.com", "api.openweathermap.org" ] }, "max_amount_usd_per_day": { "type": [ "number", "null" ], "format": "double", "description": "Maximum cumulative amount (USD) per UTC day. **Advisory only — not yet enforced.** Stored for forward compatibility; the authority currently checks only `max_amount_usd_per_request`. `None` means no per-day cap.", "example": 100.0 }, "max_amount_usd_per_request": { "type": [ "number", "null" ], "format": "double", "description": "Maximum amount (USD) any single paid request may settle for. **Enforced** by the payment authority at policy selection. `None` means no per-request cap.", "example": 5.0 }, "max_amount_usd_per_turn": { "type": [ "number", "null" ], "format": "double", "description": "Maximum cumulative amount (USD) per agent turn. **Advisory only — not yet enforced.** Stored for forward compatibility; the authority currently checks only `max_amount_usd_per_request`. `None` means no per-turn cap.", "example": 20.0 }, "metadata": { "description": "Free-form metadata attached to this policy.\nExample: `{\"owner_team\": \"ops\", \"ticket\": \"OPS-1248\"}`." }, "payment_account_id": { "type": "string", "description": "Payment account this policy authorizes spending from. Accepts a prefixed `payacct_…`\nidentifier or a bare UUID.", "example": "payacct_01933b5a00007000800000000000001" }, "rail_preference": { "type": "array", "items": { "type": "string" }, "description": "Preferred settlement rails in priority order; the authority picks the first available.", "example": [ "x402_base", "mpp_tempo" ] }, "require_approval_above_usd": { "type": [ "number", "null" ], "format": "double", "description": "Threshold (USD) above which a request would require explicit human approval. **Advisory only — not yet enforced.** Stored for forward compatibility; no approval gate is wired up yet. `None` disables the (future) gate.", "example": 10.0 }, "subject_id": { "type": "string", "description": "Prefixed identifier of the bound subject. Must use the prefix matching `subject_type`\n(see above). Example below pairs with `subject_type = \"agent_identity\"`.", "example": "identity_01933b5a00007000800000000000001" }, "subject_type": { "type": "string", "description": "Class of subject this policy binds to. One of: `user`, `agent_identity`, `agent`, `app`, `session`, `org`.\nThe prefix on `subject_id` must match: `user`→`user_…`, `agent_identity`→`identity_…`,\n`agent`→`agent_…`, `app`→`app_…`, `session`→`session_…`, `org`→`org_…`.", "example": "agent_identity" } } }, "CreatePluginMarketplaceRequest": { "type": "object", "description": "Request body for creating a plugin marketplace.", "required": [ "name", "source_type", "source" ], "properties": { "name": { "type": "string", "description": "Unique name within the org (kebab-case, e.g. `my-org-plugins`).", "example": "everruns-plugins" }, "source": { "type": "string", "description": "Source value. For `github`: `\"owner/repo\"`. For `url`: full HTTPS URL.\nFor `local_path` (dev only): absolute filesystem path.", "example": "everruns/plugins" }, "source_type": { "type": "string", "description": "Source type: `github`, `url`, or `local_path` (dev/test only).", "example": "github" } } }, "CreateProviderRequest": { "type": "object", "description": "Request to create a new LLM provider", "required": [ "name", "provider_type" ], "properties": { "api_key": { "type": [ "string", "null" ], "description": "API key for authenticating with the provider.\nWill be encrypted at rest if encryption is configured.\n\nSingle-field convenience for simple providers and programmatic clients.\nMulti-field drivers (Bedrock, MAI) should send `credentials` instead." }, "base_url": { "type": [ "string", "null" ], "description": "Base URL for the provider's API. Required for custom endpoints.\nFor standard providers, this can be omitted to use the default URL.", "example": "https://api.openai.com/v1" }, "credentials": { "type": [ "object", "null" ], "description": "Typed credential fields keyed by the driver's declared credential-schema\nfield names. Validated against the schema and assembled into the stored\ncredential document. Takes precedence over `api_key` when present.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Display name for the provider.", "example": "OpenAI Production" }, "provider_type": { "$ref": "#/components/schemas/DriverId", "description": "The type of LLM provider (e.g., openai, anthropic)." }, "request_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderRequestOptions", "description": "Extra headers and diagnostics options applied to every request sent to\nthis provider. Omit to configure none." } ] }, "trace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderTraceConfig", "description": "Trace/observability link configuration. Stored as a per-provider override\nof the driver's default templates; omit to keep driver defaults." } ] } } }, "CreatePushConfigBody": { "type": "object", "description": "Request body for creating a per-task push config.", "required": [ "url" ], "properties": { "event_filter": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Events that trigger delivery. Defaults to `[\"terminal\"]`." }, "secret": { "type": [ "string", "null" ], "description": "Optional HMAC-SHA256 signing secret (never returned once set).", "example": "whsec_example_signing_secret_placeholder" }, "url": { "type": "string", "description": "URL to POST task events to.", "example": "https://hooks.example.com/everruns/tasks" } } }, "CreateSavedReportRequest": { "type": "object", "description": "Request body for the `create_saved_report` operation.", "required": [ "name", "query" ], "properties": { "dashboard": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SavedReportDashboardMetadata", "description": "Optional dashboard placement metadata. Omit to create a library-only\nreport that isn't pinned to any dashboard layout." } ] }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Rolling 30-day count of agents with at least one session per day, grouped by org." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "Weekly active agents — last 30 days" }, "query": { "$ref": "#/components/schemas/ReportQuery", "description": "The query this report executes when run or exported. See `ReportQuery`\nfor the full field breakdown." } } }, "CreateScheduleRequest": { "type": "object", "description": "Create schedule request", "required": [ "name", "cron_expression", "target" ], "properties": { "catch_up_missed": { "type": "boolean", "description": "Whether to catch up missed triggers (default: false)", "example": false }, "cron_expression": { "type": "string", "description": "Cron expression (5-field or 7-field). Standard `min hour day-of-month month day-of-week` form.", "example": "0 2 * * *" }, "description": { "type": [ "string", "null" ], "description": "Optional description", "example": "Fires the support-triage agent every night at 02:00 UTC" }, "enabled": { "type": "boolean", "description": "Whether schedule is enabled (default: true)", "example": true }, "max_catch_up": { "type": [ "integer", "null" ], "format": "int32", "description": "Max catch-up executions when `catch_up_missed` is true. Older missed fires are dropped.", "example": 3, "minimum": 0 }, "max_concurrent": { "type": [ "integer", "null" ], "format": "int32", "description": "Max concurrent executions. Omit for no limit beyond the worker pool's concurrency.", "example": 1, "minimum": 0 }, "name": { "type": "string", "description": "Unique name for the schedule", "example": "nightly-triage" }, "retry_policy": { "description": "Retry policy for failed executions (provider-specific JSON; see the durable engine's `RetryPolicy`).\nExample: `{\"max_attempts\": 3, \"initial_backoff_secs\": 30, \"backoff_multiplier\": 2.0}`." }, "target": { "$ref": "#/components/schemas/ScheduleTarget", "description": "Target to trigger. Variant shape is defined on `ScheduleTarget`." }, "timezone": { "type": "string", "description": "Timezone (default: UTC). IANA name (e.g. `UTC`, `America/New_York`).", "example": "UTC" } } }, "CreateSessionRequest": { "type": "object", "description": "Request to create a session", "properties": { "agent_id": { "type": [ "string", "null" ], "description": "ID of the agent to work in this session (optional, format: agent_{32-hex}).\nWhen supplied without a harness, the session inherits the agent's harness.\nMutually exclusive with `agent_name`.", "example": "agent_01933b5a00007000800000000000001" }, "agent_identity_id": { "type": [ "string", "null" ], "description": "Optional resident agent identity used for unattended/background execution.", "example": "identity_01933b5a00007000800000000000001" }, "agent_name": { "type": [ "string", "null" ], "description": "Name of the agent to work in this session (optional).\nAlternative to `agent_id` — looked up by name within the org.\nMutually exclusive with `agent_id`.", "example": "support" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Session-level capabilities (additive to agent capabilities).\nApplied after agent capabilities when building RuntimeAgent.", "example": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "web_fetch" } ] }, "goal": { "type": [ "string", "null" ], "description": "Optional objective for the session. Visible to the agent at system-prompt level.", "example": "Investigate the queue latency regression and propose a fix" }, "harness_id": { "type": [ "string", "null" ], "description": "ID of the harness for this session (format: harness_{32-hex}).\nIf omitted, the harness is derived from the agent (when one is supplied),\nelse the org default harness, else the built-in fallback. New orgs default\nthat to Generic. Mutually exclusive with `harness_name`.", "example": "harness_01933b5a00007000800000000000001" }, "harness_name": { "type": [ "string", "null" ], "description": "Harness name (e.g. \"generic\", \"deep-research\").\nAlternative to `harness_id` — looked up by name within the org.\nMutually exclusive with `harness_id`.", "example": "generic" }, "hints": { "type": [ "object", "null" ], "description": "Session-level client hints — arbitrary key-value pairs that tell the\nserver what the client can handle. These are defaults for every turn;\nper-message `controls.hints` override these key-by-key (shallow merge).\n\nThree hints decide whether a turn may pause rather than talk past the\nuser: `setup_connection`, `url_elicitation`, and `ask_user` (each names\nthe card the client renders). A pause whose hint is absent does not park\n— an unhinted `ask_user` resolves with the model's defaults (EVE-1057).", "additionalProperties": {}, "propertyNames": { "type": "string" }, "example": { "ask_user": true, "rich_media": true, "setup_connection": true, "url_elicitation": true } }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Session-level initial files (additive to agent initial_files).\nFiles with matching paths override agent/harness files; new paths are appended.", "example": [ { "content": "# Project notes\n", "path": "README.md" } ] }, "locale": { "type": [ "string", "null" ], "description": "Session locale (BCP 47, e.g. `uk-UA`).", "example": "uk-UA" }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this session.", "example": 20, "minimum": 0 }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this session only." }, "model_id": { "type": [ "string", "null" ], "description": "The ID of the LLM model to use for this session.\nOverrides the agent's default model if specified.", "example": "model_01933b5a00007000800000000000001" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs this session can reach.\nMerged with harness and agent layers (allowed: intersect, blocked: union).\nExample shape is defined on `NetworkAccessList`." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598). `true` signals\nthe provider that parallel tool calls are wanted; `false` requests at\nmost one tool call per turn and forces serial execution. Omit to inherit\nthe agent/harness preference or the provider default.", "example": true }, "source": { "type": [ "string", "null" ], "description": "How this session was started. Clients may declare only `chat` (an\ninteractive thread) or `api` (the default); every other source is\nserver-owned so the sessions facet rail stays trustworthy.", "example": "chat" }, "system_prompt": { "type": [ "string", "null" ], "description": "Optional session-level system prompt override.\nPrepended to the agent's system prompt when building RuntimeAgent.", "example": "You are debugging a production incident. Be concise and cite log lines verbatim." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering sessions.", "example": [ "debugging", "urgent" ] }, "title": { "type": [ "string", "null" ], "description": "Human-readable title for the session.", "example": "Debug login issue" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools for this session (additive to agent tools).\nThese tools are sent to the LLM but executed by the client.", "example": [ { "description": "Open URL in the user's browser", "name": "open_url", "parameters": { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "type": "client_side" } ] }, "workspace_id": { "type": [ "string", "null" ], "description": "Attach this session to an existing Workspace (format: `wsp_<32-hex>`)\ninstead of auto-creating a default per-session workspace. The workspace\nmust exist in the caller's org and be `active`. Lets multiple sessions\nshare one working filesystem. Omit for the default 1:1 behavior.", "example": "wsp_01933b5a00007000800000000000001" } } }, "CreateSkillRequest": { "type": "object", "description": "Request to create a skill from SKILL.md content", "required": [ "skill_md" ], "properties": { "skill_md": { "type": "string", "description": "Full SKILL.md content (YAML frontmatter + markdown body)", "example": "---\nname: pdf-processing\ndescription: Extract text from PDFs.\n---\n\n# PDF Processing\n\nUse pdfplumber..." } } }, "CreateTaskWebhookRequest": { "type": "object", "description": "Request body for creating a task webhook.", "required": [ "url" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the webhook starts enabled. Defaults to true." }, "secret": { "type": [ "string", "null" ], "description": "Optional HMAC-SHA256 signing secret. When set, every delivery includes\nan `X-Everruns-Signature: sha256=` header." }, "url": { "type": "string", "description": "The URL to POST task terminal-state events to." } } }, "CreateWorkspaceRequest": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "example": "Shared workspace for the Q4 research project" }, "name": { "type": "string", "example": "team-research" } } }, "CredentialCheckResult": { "oneOf": [ { "type": "object", "description": "The provider accepted the credential.", "required": [ "models", "status" ], "properties": { "models": { "type": "integer", "description": "Number of models the provider listed for this credential.", "example": 42, "minimum": 0 }, "status": { "type": "string", "enum": [ "valid" ] } } }, { "type": "object", "description": "The provider rejected the credential (401/403). Hard stop.", "required": [ "message", "status" ], "properties": { "message": { "type": "string", "description": "User-facing reason. Never carries the provider's response body.", "example": "The provider rejected this API key." }, "status": { "type": "string", "enum": [ "rejected" ] } } }, { "type": "object", "description": "This driver has no credential-checking endpoint (custom base URL,\nsimulator, or a driver without model discovery).", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "unsupported" ] } } }, { "type": "object", "description": "The provider could not be reached, so the credential is unproven.", "required": [ "message", "status" ], "properties": { "message": { "type": "string", "description": "User-facing reason. Never carries the provider's response body.", "example": "Could not reach the provider to verify this API key." }, "status": { "type": "string", "enum": [ "unreachable" ] } } } ], "description": "Outcome of checking a candidate provider credential." }, "CredentialFormSchema": { "type": "object", "description": "Describes the form fields and instructions for entering a credential.", "required": [ "fields", "instructions_markdown" ], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FormField" }, "description": "Input fields to render." }, "instructions_markdown": { "type": "string", "description": "Markdown instructions shown above the form (how to get the key, etc.)." } } }, "DatabaseInfoResponse": { "type": "object", "description": "Database info response.", "required": [ "name", "size_bytes", "page_count", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "description": "Timestamp when this resource was created (RFC 3339)." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "page_count": { "type": "integer", "format": "int32" }, "size_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "DatasetCatalog": { "type": "object", "description": "Listing of every dataset the reporting layer can answer queries over.\nReturned from `GET /v1/reports/catalog`.", "required": [ "datasets" ], "properties": { "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetCatalogEntry" }, "description": "All datasets the caller has access to, in stable alphabetical order." } } }, "DatasetCatalogEntry": { "type": "object", "description": "A single dataset entry in the reporting catalog — the set of dimensions,\nmeasures, and filter fields the dataset exposes to query authors.", "required": [ "name", "dimensions", "measures", "filter_fields" ], "properties": { "dimensions": { "type": "array", "items": { "type": "string" }, "description": "Dimensions available to group by." }, "filter_fields": { "type": "array", "items": { "type": "string" }, "description": "Fields valid as the `field` of a `ReportFilter`." }, "measures": { "type": "array", "items": { "type": "string" }, "description": "Measures available to aggregate." }, "name": { "type": "string", "description": "Dataset identifier as passed to `ReportQuery.dataset`." } } }, "DatasetProjectorLag": { "type": "object", "description": "Per-dataset projector freshness telemetry. One entry per active dataset\nthe reporting projector is materializing.", "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "description": "Dataset name (matches `ReportQuery.dataset`)." }, "freshness_lag_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Gap between `latest_projected_at` and the diagnostic's\n`generated_at`, in milliseconds. `None` when freshness can't be\ndetermined." }, "latest_projected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Wall-clock timestamp of the newest fact the projector has\nmaterialized for this dataset (RFC 3339). `None` if the projector\nhasn't produced any rows yet." } } }, "DeclarativeCapability": { "type": "object", "description": "Persisted, org-scoped declarative capability — a YAML/JSON-defined\nbundle of skills, files, and tool defs that an agent or harness can\nreference by `capability_id` or name.", "required": [ "id", "capability_id", "name", "description", "status", "definition", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was archived, if any (RFC 3339)." }, "capability_id": { "type": "string", "description": "Runtime capability reference. Agents and harnesses may use this or the plain unique name.", "example": "declarative:research_pack" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "definition": { "type": "object", "description": "Declarative capability payload: system prompt, skills, starter files, MCP servers, and metadata." }, "definition_error": { "type": [ "string", "null" ], "description": "Why the stored definition could not be parsed, when it could not be.\n\nPresent only for a corrupt row. The capability keeps its identity\ncolumns so a surface can name what is broken, but `definition` is the\ninert default and `definition.status` reports `retired`, so nothing\nreads it as a usable capability.", "example": "missing field `acts_as` at line 1 column 84" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was soft-deleted, if any (RFC 3339)." }, "description": { "type": "string", "description": "Short summary shown in pickers, search results, and API listings.", "example": "Adds research instructions, starter files, and MCP tools." }, "display_name": { "type": [ "string", "null" ], "description": "Human-facing label shown in the UI. Defaults to `name` when omitted.", "example": "Research Pack" }, "id": { "type": "string", "description": "Public resource ID for this persisted declarative capability.", "example": "cap_01933b5a000070008000000000000001" }, "name": { "type": "string", "description": "Stable unique name used in capability refs. Lowercase letters, numbers, and underscores.", "example": "research_pack" }, "status": { "type": "string", "description": "Lifecycle state for the resource: active, disabled, archived, or deleted.", "example": "active" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "DeferrablePolicy": { "type": "string", "description": "Controls whether a tool's full schema can be deferred (tool_search).\n\nWhen tool_search is active and a model supports it, tools marked as\n`Automatic` or `Always` will have `defer_loading: true` set, meaning\nonly the name+description are sent upfront and full parameter schemas\nare loaded on-demand by the model.", "enum": [ "never", "automatic", "always" ] }, "DeleteAccountResponse": { "type": "object", "description": "Response for account deletion", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "DeleteFileResponse": { "type": "object", "description": "Response for delete operation", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "DeleteQuery": { "type": "object", "properties": { "recursive": { "type": "boolean" } } }, "DiffQuery": { "type": "object", "description": "Query for diff endpoint", "required": [ "oid" ], "properties": { "base": { "type": [ "string", "null" ], "description": "Base commit OID (optional, defaults to parent)", "example": "9876543210fedcba9876543210fedcba98765432" }, "oid": { "type": "string", "description": "Commit OID to diff (required). 40-char hex SHA-1.", "example": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678" } } }, "DlqEntryResponse": { "type": "object", "description": "DLQ entry response", "required": [ "id", "original_task_id", "activity_id", "activity_type", "input", "attempts", "last_error", "error_history", "dead_at" ], "properties": { "activity_id": { "type": "string", "description": "Per-workflow activity ID of the failed task.", "example": "tool_call_0042" }, "activity_type": { "type": "string", "description": "Activity type name of the failed task.", "example": "tool_call" }, "attempts": { "type": "integer", "format": "int32", "description": "Number of attempts made before the task was sent to the DLQ.", "example": 5, "minimum": 0 }, "dead_at": { "type": "string", "format": "date-time", "description": "Timestamp when the task was moved to the DLQ (RFC 3339).", "example": "2026-05-27T15:26:11Z" }, "error_history": { "type": "array", "items": { "type": "string" }, "description": "Full ordered history of error messages, one per attempt.", "example": [ "connection reset", "503 Service Unavailable", "upstream gateway timeout", "upstream gateway timeout", "upstream gateway timeout" ] }, "id": { "type": "string", "format": "uuid", "description": "UUID of the DLQ entry.", "example": "dead0000-0000-0000-0000-000000000001" }, "input": { "type": "object", "description": "Task input payload at the time of failure (used for inspection and replay)." }, "last_error": { "type": "string", "description": "Most recent error message (the one that pushed the task to the DLQ).", "example": "upstream gateway timeout" }, "original_task_id": { "type": "string", "format": "uuid", "description": "Task ID that was originally retried and ultimately failed (matches the `tasks` record before its move to the DLQ).", "example": "550e8400-e29b-41d4-a716-446655440000" }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Owning workflow's identifier, if the task was part of one.", "example": "9a1b2c3d-4e5f-6789-abcd-ef0123456789" } } }, "DlqListResponse": { "type": "object", "description": "DLQ list response", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DlqEntryResponse" }, "description": "Page of items returned by this query." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages.", "minimum": 0 } } }, "DriverCredentialInfo": { "type": "object", "description": "A driver's declared credential schema, so the Settings UI can render\ndiscrete typed inputs (multi-field AWS keys, Entra OAuth fields) instead of\none opaque password field.", "required": [ "driver", "credential_schema", "supports_oauth" ], "properties": { "credential_schema": { "$ref": "#/components/schemas/CredentialFormSchema", "description": "The fields and instructions to render for this driver's credential." }, "driver": { "type": "string", "description": "Driver id (e.g. `openai`, `bedrock`, `mai`)." }, "supports_oauth": { "type": "boolean", "description": "Whether the driver declares an interactive \"Connect with …\" OAuth flow." } } }, "DriverId": { "type": "string", "description": "LLM provider type. Built-in: openai, openrouter, azure_openai, openai_completions, anthropic, gemini, llmsim, bedrock, mai, fireworks, meta. Any other string is treated as an embedder-defined external provider." }, "ElicitationConsentRequest": { "type": "object", "description": "Request to answer a pending URL mode elicitation.", "required": [ "tool_call_id", "action" ], "properties": { "action": { "$ref": "#/components/schemas/ConsentAction", "description": "The user's decision." }, "tool_call_id": { "type": "string", "description": "The `confirm_url_elicitation` tool call being answered.", "example": "url_elicitation_01933b5a00007000800000000000001" } } }, "ElicitationConsentResponse": { "type": "object", "description": "Result of answering a pending URL mode elicitation.", "required": [ "host", "status" ], "properties": { "host": { "type": "string", "description": "Domain the consent was recorded against, echoed so a client can confirm\nit showed the same one." }, "status": { "type": "string", "description": "Session status after the decision." } } }, "EndpointStatus": { "type": "string", "description": "Per-endpoint lifecycle (EVE-1007).\n\nThis is the authority for whether an exposure accepts traffic. It replaced\nthe two-dimensional `App.status × AppChannel.enabled` matrix, which could\nexpress \"published App, disabled channel\" and forced publishing a whole App —\nand therefore every sibling endpoint on it — to make one endpoint reachable.\n\nLiveness is not this value alone; see `endpoint_is_live` in\n`crates/server/src/api/app_ingress.rs` for the agent-level terms, which are\nfolded in at resolution time rather than stored here.", "enum": [ "draft", "live", "disabled" ], "example": "live" }, "EnqueueTaskOptions": { "type": "object", "description": "Options for enqueuing a standalone task", "properties": { "max_attempts": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum retry attempts (default: 3)", "example": 3, "minimum": 0 }, "priority": { "type": [ "integer", "null" ], "format": "int32", "description": "Priority (higher = claimed first, default: 0)", "example": 10 } } }, "EnqueueTaskRequest": { "type": "object", "description": "Request body for enqueuing a standalone task (generic queue)", "required": [ "activity_type", "input" ], "properties": { "activity_type": { "type": "string", "description": "Activity type (determines which worker handles this task)", "example": "session.run" }, "input": { "description": "Task input payload (activity-specific JSON; any shape — object, array, string, etc.).\nExample for `session.run`: `{\"session_id\": \"session_01933b5a00007000800000000000001\"}`." }, "options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EnqueueTaskOptions", "description": "Retry policy options" } ] } } }, "EnqueueTaskResponse": { "type": "object", "description": "Response for enqueued task", "required": [ "task_id" ], "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Durable task's identifier." } } }, "EnvironmentCapabilities": { "type": "object", "description": "What the environment can actually do.\n\nRead this before assuming a shell behaves like Linux. Bashkit reports\n`native_processes: false`, which is why a build fails there; the answer is\navailable before the first turn rather than after a confusing tool error.", "required": [ "native_processes", "packages", "pty", "ports", "portable_checkpoint", "network_enforced" ], "properties": { "native_processes": { "type": "boolean" }, "network_enforced": { "type": "boolean" }, "packages": { "type": "boolean" }, "portable_checkpoint": { "type": "boolean" }, "ports": { "type": "boolean" }, "pty": { "type": "boolean" } } }, "EnvironmentContainment": { "type": "object", "description": "What commands may touch, and who enforces it.", "required": [ "level", "network" ], "properties": { "level": { "type": "string", "description": "`none`, `native`, or `isolated`." }, "network": { "type": "string", "description": "Outbound network policy: `deny`, `allowlist`, or `allow`." } } }, "EnvironmentTarget": { "type": "object", "description": "Where a session's commands run.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "description": "Shape of the target: `host`, `machine`, `vfs`, `container`, `managed`." }, "provider": { "type": [ "string", "null" ], "description": "Concrete provider, when the kind has one (`bashkit`, `daytona`, ...)." } } }, "EnvironmentTargetDescriptor": { "type": "object", "description": "One target this deployment can offer, and what it can do.", "required": [ "kind", "available", "capabilities", "containment_levels", "durability" ], "properties": { "available": { "type": "boolean", "description": "Whether this deployment can actually run it right now." }, "capabilities": { "$ref": "#/components/schemas/EnvironmentCapabilities" }, "containment_levels": { "type": "array", "items": { "type": "string" }, "description": "Containment levels this target supports, weakest first." }, "durability": { "type": "string" }, "kind": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ], "description": "Why it is unavailable. Present only when `available` is false." } } }, "EnvironmentTargetsResponse": { "type": "object", "description": "Response body for the `list_environment_targets` operation.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentTargetDescriptor" } } } }, "ErrorResponse": { "type": "object", "description": "Standard error response.\n\nWire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457):\nevery error response includes `title` and `status`, and may include\n`detail`, `code`, `allowed_actions`, `retry_after_seconds`, `instance`,\nand `type`. The content type is rewritten to `application/problem+json`\nby [`problem_json_content_type`].", "required": [ "title", "status" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "Recovery actions the caller can take next." }, "code": { "type": [ "string", "null" ], "description": "Stable, machine-readable error code (snake_case).", "example": "session_not_found" }, "detail": { "type": [ "string", "null" ], "description": "Human-readable explanation specific to this occurrence.", "example": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001." }, "instance": { "type": [ "string", "null" ], "description": "Request URI for this occurrence.", "example": "/v1/sessions/session_01933b5a000070008000000000000001" }, "retry_after_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Seconds the caller should wait before retrying (429 / transient 503).", "example": 30, "minimum": 0 }, "status": { "type": "integer", "format": "int32", "description": "HTTP status code; mirrors the response status line.", "example": 404, "minimum": 0 }, "title": { "type": "string", "description": "Short, human-readable summary of the problem (e.g. \"Not Found\").", "example": "Session not found" }, "type": { "type": [ "string", "null" ], "description": "RFC 9457 problem type URI. Optional; identifies the problem class.", "example": "https://docs.everruns.com/errors/session_not_found" } } }, "Event": { "type": "object", "description": "Standard event following the Everruns event protocol.\n\nAll events have a consistent structure:\n- `id`: Unique event identifier (format: event_{32-hex})\n- `type`: Event type in dot notation (e.g., \"input.message\", \"reason.started\")\n- `ts`: ISO 8601 timestamp with millisecond precision\n- `session_id`: Session this event belongs to (format: session_{32-hex})\n- `context`: Correlation context for tracing\n- `data`: Event-specific payload (typed via EventData enum)\n- `metadata`: Optional arbitrary metadata\n- `tags`: Optional list of tags for filtering", "required": [ "id", "type", "ts", "session_id", "context", "data" ], "properties": { "context": { "$ref": "#/components/schemas/EventContext", "description": "Correlation context" }, "data": { "$ref": "#/components/schemas/EventData", "description": "Event-specific payload. The schema depends on the event type.\nSee EventData documentation for the mapping of type to data schema." }, "id": { "type": "string", "description": "Unique event identifier (format: event_{32-hex})", "example": "event_01933b5a00007000800000000000001" }, "metadata": { "description": "Arbitrary metadata for the event" }, "sequence": { "type": [ "integer", "null" ], "format": "int32", "description": "Sequence number within session (for ordering)" }, "session_id": { "type": "string", "description": "Session this event belongs to (format: session_{32-hex})", "example": "session_01933b5a00007000800000000000001" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tags for filtering and categorization" }, "ts": { "type": "string", "format": "date-time", "description": "Event timestamp" }, "type": { "type": "string", "description": "Event type in dot notation" } } }, "EventContext": { "type": "object", "description": "Context for event correlation and tracing\n\nUses OpenTelemetry-style trace/span IDs for observability correlation:\n- `trace_id`: Root of the trace (typically the turn_id string)\n- `span_id`: This event's unique span identifier\n- `parent_span_id`: The parent span's identifier for hierarchical linking", "properties": { "exec_id": { "type": [ "string", "null" ], "description": "Atom execution identifier", "example": "exec_01933b5a00007000800000000000001" }, "input_message_id": { "type": [ "string", "null" ], "description": "User message that triggered this turn", "example": "message_01933b5a00007000800000000000001" }, "parent_span_id": { "type": [ "string", "null" ], "description": "Parent span ID for hierarchical linking (OTel-style).\nLinks this span to its parent in the trace hierarchy." }, "span_id": { "type": [ "string", "null" ], "description": "This event's span ID for observability (OTel-style).\nUniquely identifies this span within the trace." }, "trace_id": { "type": [ "string", "null" ], "description": "Trace ID for observability (OTel-style). Groups related spans into a single trace.\nFor agent turns, this is typically the turn_id string." }, "turn_id": { "type": [ "string", "null" ], "description": "Turn identifier (for turn-scoped events)", "example": "turn_01933b5a00007000800000000000001" } } }, "EventData": { "oneOf": [ { "$ref": "#/components/schemas/InputMessageData" }, { "$ref": "#/components/schemas/OutputMessageDeltaData" }, { "$ref": "#/components/schemas/OutputMessageStartedData" }, { "$ref": "#/components/schemas/OutputMessageReplacedData" }, { "$ref": "#/components/schemas/OutputMessageCompletedData" }, { "$ref": "#/components/schemas/TurnStartedData" }, { "$ref": "#/components/schemas/TurnCompletedData" }, { "$ref": "#/components/schemas/TurnFailedData" }, { "$ref": "#/components/schemas/ReasonStartedData" }, { "$ref": "#/components/schemas/ReasonCompletedData" }, { "$ref": "#/components/schemas/ReasonRecoveredData" }, { "$ref": "#/components/schemas/CapabilityUsageData" }, { "$ref": "#/components/schemas/ActStartedData" }, { "$ref": "#/components/schemas/ActCompletedData" }, { "$ref": "#/components/schemas/ToolStartedData" }, { "$ref": "#/components/schemas/ToolCompletedData" }, { "$ref": "#/components/schemas/ToolProgressData" }, { "$ref": "#/components/schemas/ToolOutputDeltaData" }, { "$ref": "#/components/schemas/ToolCallRequestedData" }, { "$ref": "#/components/schemas/TranscriptRepairedData" }, { "$ref": "#/components/schemas/ToolCallRepairedData" }, { "$ref": "#/components/schemas/LlmGenerationData" }, { "$ref": "#/components/schemas/ReasonThinkingDeltaData" }, { "$ref": "#/components/schemas/ReasonItemData" }, { "$ref": "#/components/schemas/ReasonThinkingStartedData" }, { "$ref": "#/components/schemas/ReasonThinkingCompletedData" }, { "$ref": "#/components/schemas/TurnSealedData" }, { "$ref": "#/components/schemas/TurnCancelledData" }, { "$ref": "#/components/schemas/SessionStartedData" }, { "$ref": "#/components/schemas/SessionActivatedData" }, { "$ref": "#/components/schemas/SessionIdledData" }, { "$ref": "#/components/schemas/SessionTitleUpdatedData" }, { "$ref": "#/components/schemas/SessionModelChangedData" }, { "$ref": "#/components/schemas/SessionTaskEventData" }, { "$ref": "#/components/schemas/SessionTaskEventData" }, { "$ref": "#/components/schemas/TaskMessageEventData" }, { "$ref": "#/components/schemas/TaskMessageEventData" }, { "$ref": "#/components/schemas/ContextCompactingData" }, { "$ref": "#/components/schemas/ContextCompactedData" }, { "$ref": "#/components/schemas/ContextCompactionSkippedData", "description": "Evaluation ran but installed nothing (context.compaction.skipped)." }, { "$ref": "#/components/schemas/ContextCompactionFailedData", "description": "Attempt errored before installing (context.compaction.failed)." }, { "$ref": "#/components/schemas/FileWrittenData" }, { "$ref": "#/components/schemas/BudgetEventData" }, { "$ref": "#/components/schemas/BudgetEventData" }, { "$ref": "#/components/schemas/BudgetEventData" }, { "$ref": "#/components/schemas/BudgetEventData" }, { "$ref": "#/components/schemas/VoiceSessionStartedData" }, { "$ref": "#/components/schemas/VoiceTranscriptData" }, { "$ref": "#/components/schemas/VoiceTranscriptData" }, { "$ref": "#/components/schemas/VoiceTranscriptData" }, { "$ref": "#/components/schemas/VoiceTranscriptData" }, { "$ref": "#/components/schemas/VoiceSessionEndedData" }, { "$ref": "#/components/schemas/VoiceSessionFailedData" } ], "title": "EventData", "description": "Event-specific payload. The schema depends on the event type field.", "example": { "message": { "content": [], "id": "...", "role": "user" } } }, "EventTypeCountOut": { "type": "object", "description": "One row of `EventsSummaryResult.by_type` — the per-event-type count\nproduced by the events summary query.", "required": [ "event_type", "count" ], "properties": { "count": { "type": "integer", "format": "int64", "description": "Count of items matching the query." }, "event_type": { "type": "string", "description": "Event-type discriminator (e.g. `turn.started`, `tool.completed`)." } } }, "EventsSummaryResult": { "type": "object", "description": "Aggregate result of the events summary query — total count, per-type\nbreakdown, and a few convenience rollups (turn count, failure count).", "required": [ "total", "by_type", "turn_count", "error_count" ], "properties": { "by_type": { "type": "array", "items": { "$ref": "#/components/schemas/EventTypeCountOut" }, "description": "Per-type count, sorted by event_type asc." }, "error_count": { "type": "integer", "format": "int64", "description": "Convenience: count of failure-shaped event types\n(`turn.failed`, `tool.failed`, `*.error`, `subagent.failed`)." }, "first_ts": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest event timestamp, if any." }, "last_ts": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest event timestamp, if any." }, "total": { "type": "integer", "format": "int64", "description": "Total event count across all types." }, "turn_count": { "type": "integer", "format": "int64", "description": "Convenience: count of `turn.started` events." } } }, "ExecutionPhase": { "type": "string", "description": "Execution phase for assistant messages in multi-step tool-calling flows.\n\nProviders that natively support phases (OpenAI GPT-5.x) send the phase value\ndirectly in the API request. For providers without native support (Anthropic,\nGemini), the phase is still tracked internally and derived from state in the\nReasonAtom, but is not sent to the provider API.\n\nSerialized as lowercase strings for backward compatibility with existing\npersisted messages: `\"commentary\"` and `\"final_answer\"`.\n\nLegacy values `\"in_progress\"` and `\"completed\"` are accepted during\ndeserialization for backward compatibility.", "enum": [ "commentary", "final_answer" ] }, "ExportReportQueryRequest": { "type": "object", "description": "Request body for the `export_report_query` operation.", "required": [ "query" ], "properties": { "format": { "$ref": "#/components/schemas/ReportExportFormat", "description": "Export format. Defaults to `csv` when omitted." }, "query": { "$ref": "#/components/schemas/ReportQuery", "description": "Ad-hoc query to materialize and export. Same shape as the body of\n`POST /v1/reports/query` — see `ReportQuery` for the field breakdown." } } }, "ExportSavedReportRequest": { "type": "object", "description": "Request body for the `export_saved_report` operation.", "properties": { "format": { "$ref": "#/components/schemas/ReportExportFormat", "description": "Export format. Defaults to `csv` when omitted." } } }, "ExportUserDataResponse": { "type": "object", "description": "Full user data export response (GDPR compliance)", "required": [ "user", "organizations", "personal_access_tokens", "exported_at" ], "properties": { "exported_at": { "type": "string", "format": "date-time", "description": "Timestamp the export was generated (RFC 3339).", "example": "2026-05-25T12:00:00Z" }, "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/ExportedOrganization" }, "description": "All organizations the user is a member of, plus their role in each." }, "personal_access_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ExportedPersonalAccessToken" }, "description": "Personal access tokens owned by the user (no sensitive secrets — just metadata)." }, "user": { "$ref": "#/components/schemas/ExportedUserProfile", "description": "Profile data for the exporting user." } } }, "ExportedOrganization": { "type": "object", "description": "Exported organization membership", "required": [ "org_id", "public_id", "name", "role" ], "properties": { "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "Acme Corp" }, "org_id": { "type": "integer", "format": "int64", "description": "Owning organization's internal numeric id (not part of the public identifier surface).", "example": 42 }, "public_id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "org_01933b5a000070008000000000000001" }, "role": { "type": "string", "description": "User's role within this organization (`owner`, `admin`, `member`).", "example": "owner" } } }, "ExportedPersonalAccessToken": { "type": "object", "description": "Exported personal access token metadata (no sensitive data)", "required": [ "id", "name", "token_prefix", "scopes", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339).", "example": "2026-01-15T10:30:00Z" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiry timestamp (RFC 3339). `None` for non-expiring tokens.", "example": "2027-01-01T00:00:00Z" }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "019e8957539a7aa0bb92e0d2b49427b1" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the token's most recent successful use (RFC 3339). `None` if never used.", "example": "2026-05-25T09:14:00Z" }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "CI/CD deploy token" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Granted scopes as a JSON array of strings.", "example": [ "sessions:read", "sessions:write" ] }, "token_prefix": { "type": "string", "description": "First few characters of the token, safe to display for identification.", "example": "evr_pat_x4z2..." } } }, "ExportedUserProfile": { "type": "object", "description": "Exported user profile data", "required": [ "id", "email", "name", "email_verified", "created_at", "updated_at" ], "properties": { "auth_provider": { "type": [ "string", "null" ], "description": "Auth provider that issued this identity (`google`, `github`, `password`, etc.).", "example": "google" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to the user's avatar image. `None` when the user hasn't set one.", "example": "https://cdn.example.com/avatars/alex.png" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339).", "example": "2026-01-15T10:30:00Z" }, "email": { "type": "string", "description": "Email address associated with the user account.", "example": "alex@example.com" }, "email_verified": { "type": "boolean", "description": "Whether the user's email address has been verified via the auth provider.", "example": true }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "user_01933b5a000070008000000000000001" }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "Alex Rivera" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339).", "example": "2026-04-20T14:22:00Z" } } }, "ExternalActor": { "type": "object", "description": "External actor identity for messages originating from external channels\n(Slack, Discord, Teams, etc.).\n\nChannel adapters populate this to identify the sender without coupling\ncore logic to any specific channel. The ReasonAtom uses this to prefix\nuser messages so the LLM knows who is speaking.", "required": [ "actor_id", "source" ], "properties": { "actor_id": { "type": "string", "description": "Opaque actor identifier from the source channel (e.g. Slack user ID \"U0123456789\")" }, "actor_name": { "type": [ "string", "null" ], "description": "Resolved display name (e.g. \"Alice\"). Falls back to actor_id if absent." }, "metadata": { "type": [ "object", "null" ], "description": "Channel-specific metadata (e.g. team_id, channel_id)", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "source": { "type": "string", "description": "Source channel identifier (e.g. \"slack\", \"discord\")" } } }, "FailedReportingOutboxRow": { "type": "object", "description": "One failed reporting-outbox row, surfaced in\n`ReportingOutboxDiagnostics.failed_rows` so operators can triage\nprojector failures without dropping to SQL.", "required": [ "id", "org_id", "source_type", "source_id", "attempts", "updated_at" ], "properties": { "attempts": { "type": "integer", "format": "int32", "description": "Number of processing attempts made before this row was marked failed." }, "id": { "type": "string", "format": "uuid", "description": "Outbox row UUID." }, "last_error": { "type": [ "string", "null" ], "description": "Most recent error message from a processing attempt." }, "org_id": { "type": "integer", "format": "int64", "description": "Owning organization's internal numeric id." }, "source_id": { "type": "string", "description": "Source-specific row identifier (event id, session id, etc.)." }, "source_type": { "type": "string", "description": "Discriminator for the outbox source (`event`, `session`, `llm_generation`, `usage_ledger`)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this row was last updated (RFC 3339)." } } }, "FeatureFlagMap": { "type": "object", "description": "Untyped API representation of feature flags: a generic `{ \"\": bool }` map.\n\nDecision: the public API is intentionally untyped. The set of flags churns\nfrequently; encoding each flag as a named schema property would force a\n`docs/api/openapi.json` change on every add/remove. A generic string→bool map\nkeeps the API spec stable. The frontend layers its own typed view on top.", "additionalProperties": { "type": "boolean" }, "propertyNames": { "type": "string" } }, "FieldType": { "type": "string", "description": "Input field type for rendering.", "enum": [ "password", "text", "url" ] }, "FileContentPart": { "type": "object", "description": "File content part (reference to an uploaded file, e.g. a PDF)\n\nThis is used for files uploaded via the /files API.\nThe file data is stored separately and referenced by ID.", "required": [ "file_id" ], "properties": { "file_id": { "type": "string", "description": "ID of the uploaded file (format: file_{32-hex})", "example": "file_01933b5a00007000800000000000001" }, "filename": { "type": [ "string", "null" ], "description": "Original filename (for display and provider file parts)" } } }, "FileInfo": { "type": "object", "description": "Stored file metadata (no binary data).", "required": [ "id", "content_type", "size_bytes", "metadata", "created_at" ], "properties": { "content_type": { "type": "string", "description": "MIME type of the stored file (currently always application/pdf).", "example": "application/pdf" }, "created_at": { "type": "string", "format": "date-time", "description": "Upload timestamp.", "example": "2026-01-04T11:23:00Z" }, "filename": { "type": [ "string", "null" ], "description": "Original filename supplied at upload, if known.", "example": "report.pdf" }, "id": { "type": "string", "example": "file_01933b5a00007000800000000000001" }, "metadata": { "type": "object", "description": "Caller-supplied metadata captured at upload." }, "size_bytes": { "type": "integer", "format": "int64", "description": "Size of the stored file in bytes.", "example": 1048576 } } }, "FileStat": { "type": "object", "description": "File stat information", "required": [ "path", "name", "is_directory", "is_readonly", "size_bytes", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this entry was created (RFC 3339)." }, "is_directory": { "type": "boolean", "description": "`true` when this entry represents a directory." }, "is_readonly": { "type": "boolean", "description": "Whether the entry is read-only." }, "name": { "type": "string", "description": "File or directory name (last segment of `path`)." }, "path": { "type": "string", "description": "Absolute path within the session workspace." }, "size_bytes": { "type": "integer", "format": "int64", "description": "File size in bytes. `0` for directories." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this entry was last updated (RFC 3339)." } } }, "FileUploadResponse": { "type": "object", "description": "File metadata returned after a successful upload (no binary data).", "required": [ "id", "content_type", "size_bytes", "created_at" ], "properties": { "content_type": { "type": "string", "description": "MIME type of the stored file (currently always application/pdf).", "example": "application/pdf" }, "created_at": { "type": "string", "format": "date-time", "description": "Upload timestamp.", "example": "2026-01-04T11:23:00Z" }, "filename": { "type": [ "string", "null" ], "description": "Original filename supplied at upload, if known.", "example": "report.pdf" }, "id": { "type": "string", "example": "file_01933b5a00007000800000000000001" }, "size_bytes": { "type": "integer", "format": "int64", "description": "Size of the stored file in bytes.", "example": 1048576 } } }, "FileWrittenData": { "type": "object", "description": "Data for file.written events emitted when files are written to the session filesystem.", "required": [ "path", "operation", "size_bytes", "created" ], "properties": { "created": { "type": "boolean", "description": "Whether this is a new file (true) or an update to an existing file (false)." }, "operation": { "type": "string", "description": "Operation type (see `FILE_OP_*` constants)." }, "path": { "type": "string", "description": "File path within the session filesystem (normalized, e.g. \"/reports/summary.md\")." }, "size_bytes": { "type": "integer", "format": "int64", "description": "File size in bytes after write." } } }, "Finding": { "type": "object", "description": "A single advisory finding about an agent configuration.", "required": [ "rule_id", "severity", "category", "message", "source" ], "properties": { "category": { "$ref": "#/components/schemas/FindingCategory" }, "fix": { "type": [ "string", "null" ], "description": "Proposed replacement text (phase 2+; always absent for builtin rules)." }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FindingLocation" } ] }, "message": { "type": "string", "description": "Human-readable explanation. Safe to render in user-facing messages." }, "rule_id": { "type": "string", "description": "Stable rule identifier, e.g. `prompt.duplicate_paragraphs`." }, "severity": { "$ref": "#/components/schemas/FindingSeverity" }, "source": { "$ref": "#/components/schemas/FindingSource" } } }, "FindingCategory": { "type": "string", "enum": [ "structure", "completeness", "effectiveness", "safety", "cost" ] }, "FindingLocation": { "type": "object", "description": "Pointer to the config field (and optional byte span within it) a finding\nrefers to.", "required": [ "field" ], "properties": { "end": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "field": { "type": "string", "description": "Config field name, e.g. `system_prompt`, `tools`." }, "start": { "type": [ "integer", "null" ], "format": "int32", "description": "Byte offset range into the field's authored text, when applicable.", "minimum": 0 } } }, "FindingSeverity": { "type": "string", "description": "Advisory severity. There is deliberately no `error`: checks never gate\nsave/publish (knowledge/evaluation/agent-checks.md, Non-Goals).", "enum": [ "warning", "info", "suggestion" ] }, "FindingSource": { "type": "string", "description": "Which tier produced the finding.", "enum": [ "builtin", "llm", "health_check" ] }, "ForkAgentVersionRequest": { "type": "object", "description": "Request body for the `fork_agent_version` operation.", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Fork to test new refund-flow capabilities before promoting" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name. Safe to render in user-facing messages.", "example": "Support Agent (Experimental)" }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "support-agent-experimental" } } }, "ForkSessionRequest": { "type": "object", "description": "Request to fork a session (knowledge/runtime-resources/forking-sessions.md). Every field is\noptional; omitted fields inherit the parent session's value. Title defaults\nto \"{parent title} (fork)\" when omitted.", "properties": { "agent_id": { "type": [ "string", "null" ], "description": "Override the agent assigned to the fork.", "example": "agent_01933b5a00007000800000000000001" }, "goal": { "type": [ "string", "null" ], "description": "Goal for the fork. Omitted inherits the parent's goal.", "example": "Try the async rewrite from this state" }, "locale": { "type": [ "string", "null" ], "description": "Override the locale (BCP 47).", "example": "uk-UA" }, "model_id": { "type": [ "string", "null" ], "description": "Override the LLM model for the fork.", "example": "model_01933b5a00007000800000000000001" }, "system_prompt": { "type": [ "string", "null" ], "description": "Override the session-level system prompt." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tags for the fork. Replaces (does not merge with) the parent's tags.", "example": [ "experiment" ] }, "title": { "type": [ "string", "null" ], "description": "Title for the fork. Defaults to \"{parent title} (fork)\".", "example": "Branch: try the async rewrite" } } }, "FormField": { "type": "object", "description": "A single form field.", "required": [ "name", "label", "field_type", "required" ], "properties": { "default_value": { "type": [ "string", "null" ], "description": "Default value the UI pre-fills (e.g. an OAuth scope or AWS region). The\nstored credential omits unfilled optional fields, so drivers still apply\ntheir own defaults; this only seeds the form input." }, "env": { "type": "array", "items": { "type": "string" }, "description": "Environment variables this field can be read from in standalone/dev use,\nmost preferred first.\n\nDeclared by the driver, because only the driver knows what its vendor's\nown SDK reads: `AWS_ACCESS_KEY_ID` for Bedrock, `AZURE_TENANT_ID` for\nMAI's Entra group, `ANTHROPIC_API_KEY` for Anthropic. Later entries are\nalternates the vendor also honors (`GOOGLE_API_KEY`,\n`AWS_DEFAULT_REGION`), not a second field.\n\nEmpty means the field cannot be supplied from the environment, so a\ngroup containing a required field with no variable never resolves from\nenv alone. Server credential resolution ignores this entirely." }, "field_type": { "$ref": "#/components/schemas/FieldType", "description": "Input type." }, "group": { "type": [ "string", "null" ], "description": "Mutually-exclusive group label this field belongs to. Fields sharing a\nlabel are one alternative credential method (e.g. \"API key\" vs \"OAuth\");\nungrouped fields are always part of the credential. `None` for the\ncommon single-method case." }, "help_text": { "type": [ "string", "null" ], "description": "Help text shown below the input." }, "label": { "type": "string", "description": "Label shown next to the input." }, "name": { "type": "string", "description": "Field name used as the key when submitting (e.g. \"api_key\")." }, "placeholder": { "type": [ "string", "null" ], "description": "Placeholder text inside the input." }, "required": { "type": "boolean", "description": "Whether the field is required." } } }, "GetQuery": { "type": "object", "description": "Query parameters for GET requests", "properties": { "recursive": { "type": "boolean", "description": "For directories: whether to list recursively" } } }, "GetResponse": { "oneOf": [ { "$ref": "#/components/schemas/SessionFile" }, { "$ref": "#/components/schemas/ListResponse_FileInfo" } ], "description": "Unified response for GET that can be file or directory listing" }, "GetSessionSandboxResponse": { "type": "object", "description": "Response body for the `get_session_sandbox` operation.", "required": [ "configured", "exists" ], "properties": { "configured": { "type": "boolean", "description": "Whether the session's harness opts in to a managed sandbox at all." }, "created_at": { "type": [ "string", "null" ], "description": "Timestamp when this sandbox record was created (RFC 3339)." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable sandbox label. Safe to render in user-facing messages." }, "exists": { "type": "boolean", "description": "Whether a sandbox instance currently exists for this session (within its lease)." }, "external_id": { "type": [ "string", "null" ], "description": "Provider-side sandbox identifier (workspace ID, container ID, etc.)." }, "init_completed_at": { "type": [ "string", "null" ], "description": "Timestamp when sandbox initialization finished (RFC 3339); absent while still starting." }, "last_init_error": { "type": [ "string", "null" ], "description": "Most recent initialization error message; cleared on successful re-init." }, "metadata": { "type": "object", "description": "Provider-specific metadata (URLs, ports, credentials envelopes)." }, "provider": { "type": [ "string", "null" ], "description": "Sandbox provider (`daytona`, `e2b`, `docker`, etc.) when one is configured." }, "session_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SessionSandboxStatusValue", "description": "Current sandbox lifecycle status (`starting`, `ready`, `error`, `released`)." } ] }, "updated_at": { "type": [ "string", "null" ], "description": "Timestamp when this sandbox record was last updated (RFC 3339)." }, "workspace_path": { "type": [ "string", "null" ], "description": "Absolute path of the sandbox workspace root (used to scope file operations)." } } }, "GitCommitInfo": { "type": "object", "description": "A commit entry in the log", "required": [ "oid", "message", "author_name", "author_email", "timestamp", "parent_oids" ], "properties": { "author_email": { "type": "string", "description": "Author email from the commit." }, "author_name": { "type": "string", "description": "Author display name from the commit." }, "message": { "type": "string", "description": "Commit message as authored." }, "oid": { "type": "string", "description": "Full git object identifier (40-char hex SHA-1)." }, "parent_oids": { "type": "array", "items": { "type": "string" }, "description": "Parent commit object identifiers. Length 0 for the initial commit, 1 for ordinary commits, 2+ for merge commits." }, "timestamp": { "type": "string", "format": "date-time", "description": "Commit timestamp (RFC 3339, normalised to UTC)." } } }, "GitDiff": { "type": "object", "description": "A diff with full patch output", "required": [ "entries", "stats" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/GitDiffEntry" }, "description": "Per-file change records. Empty when the two trees are identical." }, "patch": { "type": [ "string", "null" ], "description": "Unified-diff patch text covering all `entries`, truncated to ~64 KiB\n(with a trailing `... (truncated)` marker when the cap is hit).\n`None` when the diff produced no patch text — typically because the\ntwo trees are identical." }, "stats": { "$ref": "#/components/schemas/GitDiffStats", "description": "Aggregate line/file counts across `entries`." } } }, "GitDiffEntry": { "type": "object", "description": "A diff entry between two commits", "required": [ "path", "status" ], "properties": { "old_path": { "type": [ "string", "null" ], "description": "Pre-change path. Only set when `status == \"renamed\"`; otherwise\n`None` (including for `added`/`deleted`/`modified`)." }, "path": { "type": "string", "description": "File path on the \"new\" side of the diff (the post-change path). For\na rename, the pre-rename path is in `old_path`. Repo-root-relative,\nforward-slash separated." }, "status": { "type": "string", "description": "Current lifecycle status." } } }, "GitDiffStats": { "type": "object", "description": "Diff statistics", "required": [ "files_changed", "insertions", "deletions" ], "properties": { "deletions": { "type": "integer", "description": "Total removed lines summed across all files (the `-` count in a\nunified diff).", "minimum": 0 }, "files_changed": { "type": "integer", "description": "Number of files with at least one changed line (matches the length\nof `GitDiff.entries`).", "minimum": 0 }, "insertions": { "type": "integer", "description": "Total added lines summed across all files (the `+` count in a\nunified diff).", "minimum": 0 } } }, "GitHubMemorySourceRequest": { "type": "object", "description": "Request body for GitHub memory source.", "required": [ "repository" ], "properties": { "branch": { "type": [ "string", "null" ], "description": "Branch to sync. Defaults to the repository's default branch when omitted.", "example": "main" }, "repository": { "type": "string", "description": "GitHub repository in `owner/repo` form.", "example": "acme/design-docs" }, "root_folder": { "type": [ "string", "null" ], "description": "Sub-directory within the repository to sync. Empty / omitted = whole tree.", "example": "docs/" }, "sync_interval_secs": { "type": [ "integer", "null" ], "format": "int32", "description": "Automatic resync interval in seconds. Omit or set 0 for manual-only; scheduled sync accepts 300 through 604800.", "example": 3600, "maximum": 604800, "minimum": 0 } } }, "GitHubMemorySourceResponse": { "type": "object", "description": "Response body for GitHub memory source.", "required": [ "repository", "branch" ], "properties": { "branch": { "type": "string" }, "repository": { "type": "string" }, "root_folder": { "type": [ "string", "null" ] }, "sync_interval_secs": { "type": [ "integer", "null" ], "format": "int32", "description": "Automatic resync interval in seconds. Omit or set 0 for manual-only; scheduled sync accepts 300 through 604800.", "maximum": 604800, "minimum": 0 } } }, "GitMemorySourceRequest": { "type": "object", "description": "Request body for git memory source.", "required": [ "url" ], "properties": { "branch": { "type": [ "string", "null" ], "description": "Branch to sync. Defaults to the repository's default branch when omitted.", "example": "main" }, "root_folder": { "type": [ "string", "null" ], "description": "Sub-directory within the repository to sync. Empty / omitted = whole tree.", "example": "docs/" }, "sync_interval_secs": { "type": [ "integer", "null" ], "format": "int32", "description": "Automatic resync interval in seconds. Omit or set 0 for manual-only; scheduled sync accepts 300 through 604800.", "example": 3600, "maximum": 604800, "minimum": 0 }, "url": { "type": "string", "description": "Clonable git URL (SSH or HTTPS).", "example": "https://github.com/acme/design-docs.git" } } }, "GitMemorySourceResponse": { "type": "object", "description": "Response body for git memory source.", "required": [ "url", "branch" ], "properties": { "branch": { "type": "string" }, "root_folder": { "type": [ "string", "null" ] }, "sync_interval_secs": { "type": [ "integer", "null" ], "format": "int32", "description": "Automatic resync interval in seconds. Omit or set 0 for manual-only; scheduled sync accepts 300 through 604800.", "maximum": 604800, "minimum": 0 }, "url": { "type": "string" } } }, "GitRefInfo": { "type": "object", "description": "A git ref (branch pointer)", "required": [ "name", "target", "is_symbolic" ], "properties": { "is_symbolic": { "type": "boolean" }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "target": { "type": "string" } } }, "GrepMatch": { "type": "object", "description": "Grep match result", "required": [ "path", "line_number", "line" ], "properties": { "line": { "type": "string" }, "line_number": { "type": "integer", "minimum": 0 }, "path": { "type": "string" } } }, "GrepRequest": { "type": "object", "required": [ "pattern" ], "properties": { "path_pattern": { "type": [ "string", "null" ], "description": "Optional path glob (`**/*.rs`, `docs/*.md`)." }, "pattern": { "type": "string", "description": "Regex pattern to search for." } } }, "GrepResult": { "type": "object", "description": "Grep result for a file", "required": [ "path", "matches" ], "properties": { "matches": { "type": "array", "items": { "$ref": "#/components/schemas/GrepMatch" } }, "path": { "type": "string" } } }, "GuardrailAction": { "type": "string", "description": "Effective action of a hit after applying the config mode.", "enum": [ "block", "log" ], "example": "block" }, "GuardrailExample": { "type": "object", "description": "A read-only, adoptable guardrails preset from the gallery. Adopt by\ndropping `config` into an agent's `guardrails` capability config.", "required": [ "name", "display_name", "description", "tags", "check_types", "stages", "data_egress", "config" ], "properties": { "check_types": { "type": "array", "items": { "type": "string" }, "description": "Distinct rule types used across the preset's checks\n(`regex`, `blocklist`, `tool_pattern`) — the check-type composition." }, "config": { "type": "object", "description": "The adoptable `GuardrailsConfig`. Same shape persisted in\n`AgentCapabilityConfig.config` for the `guardrails` capability." }, "data_egress": { "type": "string", "description": "Where the preset sends data when it runs. `none` for deterministic\npresets (everything runs in-process).", "example": "none" }, "description": { "type": "string", "description": "What the preset protects against and how to tune it." }, "display_name": { "type": "string", "description": "Human-facing label.", "example": "Secret & Credential Detection" }, "name": { "type": "string", "description": "Stable slug used to reference the preset (e.g. `secret-detection`).", "example": "secret-detection" }, "stages": { "type": "array", "items": { "type": "string" }, "description": "Distinct stages the preset's checks run in (`output`, `tool_use`,\n`tool_output`)." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for grouping/filtering in a picker." } } }, "GuardrailExamplesResponse": { "type": "object", "description": "Response for the `list_guardrail_examples` operation.", "required": [ "examples" ], "properties": { "examples": { "type": "array", "items": { "$ref": "#/components/schemas/GuardrailExample" }, "description": "Adoptable guardrail presets, in display order." } } }, "GuardrailStage": { "type": "string", "description": "Pipeline stage a check applies to.", "enum": [ "output", "tool_use", "tool_output" ], "example": "output" }, "GuardrailsDryRunHit": { "type": "object", "description": "One triggered check from a guardrails dry run.", "required": [ "check_index", "check_id", "stage", "rule_type", "action", "reason_code" ], "properties": { "action": { "$ref": "#/components/schemas/GuardrailAction", "description": "Effective action (advisory mode downgrades block to log)." }, "check_id": { "type": "string", "description": "The check's `id`, or `\"#\"` when none was set.", "example": "profanity" }, "check_index": { "type": "integer", "format": "int32", "description": "Index of the check in the config's `checks` array.", "minimum": 0 }, "matched": { "type": [ "string", "null" ], "description": "Bounded excerpt of what matched.", "example": "darn" }, "reason_code": { "type": "string", "description": "Stable machine-readable code, `guardrail.`.", "example": "guardrail.blocklist" }, "replacement": { "type": [ "string", "null" ], "description": "The check's custom replacement text, if configured." }, "rule_type": { "type": "string", "description": "Rule type: regex, blocklist, or tool_pattern.", "example": "blocklist" }, "stage": { "$ref": "#/components/schemas/GuardrailStage", "description": "Stage the check ran in." } } }, "GuardrailsDryRunRequest": { "type": "object", "description": "Request body for the `dry_run_guardrails` operation: evaluate a\nguardrails capability config against sample content without a session.", "required": [ "config", "stage", "text" ], "properties": { "config": { "type": "object", "description": "The `guardrails` capability config to evaluate (same shape persisted\nin `AgentCapabilityConfig.config`)." }, "stage": { "$ref": "#/components/schemas/GuardrailStage", "description": "Pipeline stage to evaluate." }, "text": { "type": "string", "description": "Sample content: model output, serialized tool arguments, or tool\noutput, depending on `stage`.", "example": "the model said something darn surprising" }, "tool_name": { "type": [ "string", "null" ], "description": "Tool name for `tool_use` stage checks (`tool_pattern` rules).", "example": "bashkit_exec" } } }, "GuardrailsDryRunResponse": { "type": "object", "description": "Response for the `dry_run_guardrails` operation.", "required": [ "hits", "blocked" ], "properties": { "blocked": { "type": "boolean", "description": "Whether any hit would block (i.e. the content would be suppressed\nor the tool call refused when this config runs active)." }, "hits": { "type": "array", "items": { "$ref": "#/components/schemas/GuardrailsDryRunHit" }, "description": "All triggered checks, in config order." } } }, "Harness": { "type": "object", "description": "Harness configuration for sessions.\nA harness defines the base behavior and capabilities that apply to all sessions.", "required": [ "id", "name", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was archived.", "example": "2026-05-26T00:00:00Z" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities enabled for this harness with per-harness configuration." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was created.", "example": "2026-04-01T10:00:00Z" }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model ID for this harness.\nLowest priority in chain: controls > session > agent > harness.", "example": "model_01933b5a00007000800000000000001" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was deleted.", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the harness does.", "example": "Default harness with file-system + secrets capabilities; safe baseline for new agents." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI.", "example": "Generic Harness" }, "embedder_metadata": { "type": "object", "description": "Arbitrary key-value metadata injected into LLM requests for observability.\nKeys from system context (session_id, org_id, etc.) always take precedence.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": { "env": "production", "team": "platform" } }, "icon": { "type": [ "string", "null" ], "description": "Display glyph name rendered by the UI (e.g. \"message-circle\").\n\nBuilt-in harnesses declare it in their definition; custom harnesses\nleave it unset and fall back to the UI's generic harness glyph.", "example": "message-circle" }, "id": { "type": "string", "description": "Unique identifier for the harness (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this harness." }, "intro_markdown": { "type": [ "string", "null" ], "description": "Optional Markdown intro rendered as an intro box at the top of a fresh\nPlatform Chat thread. Images are allowed. The agent intro wins over\nthe harness intro. Hidden once the user inputs.", "example": "I can triage incidents, dig through logs, and draft the update." }, "is_built_in": { "type": "boolean", "description": "Whether this harness is built-in (system-managed, readonly).\nBuilt-in harnesses are provisioned during org initialization and\ncannot be modified or deleted via the API. Users can copy them.", "example": false }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this harness and inherited by descendant layers." }, "name": { "type": "string", "description": "Name, unique per org (e.g. \"generic\").", "example": "generic" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs sessions can reach.\nMerged with agent and session layers (allowed: intersect, blocked: union)." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "parent_harness_id": { "type": [ "string", "null" ], "description": "Optional parent harness that this harness inherits from.", "example": "harness_01933b5a000070008000000000000602" }, "short_description": { "type": [ "string", "null" ], "description": "Optional one-line description in simplified Markdown, shown below the\nchat title once the intro is hidden. The agent value wins.", "example": "Knows your agents, harnesses, models, and runs." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. The agent's\nstarters win when non-empty, otherwise the harness's apply." }, "status": { "$ref": "#/components/schemas/HarnessStatus", "description": "Current lifecycle status of the harness." }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt that defines the harness's base behavior.\n\nForms the foundation of the prompt stack. Optional: when absent the\nharness contributes no base prompt, so the effective prompt comes\nentirely from the parent harness (if any), the agent, the session, and\ncapability contributions. Empty/whitespace-only values normalize to\n`None`.", "example": "You are an Everruns agent. Be concise, cite sources when possible, and decline tasks outside your assigned scope." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering harnesses.", "example": [ "baseline", "production" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was last updated.", "example": "2026-05-20T14:00:00Z" } } }, "HarnessExample": { "type": "object", "description": "A read-only harness example defined in code.", "required": [ "name", "display_name", "description", "tags", "capabilities", "dev_only" ], "properties": { "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities the example will assign with their per-harness config." }, "description": { "type": "string", "description": "Short description." }, "dev_only": { "type": "boolean", "description": "Whether this example is only available when experimental features are on." }, "display_name": { "type": "string", "description": "Human-readable display name (e.g. `Data Analyst`)." }, "icon": { "type": [ "string", "null" ], "description": "Display glyph name rendered by the UI (e.g. `bar-chart`)." }, "name": { "type": "string", "description": "Unique slug (e.g. `data-analyst`)." }, "parent_name": { "type": [ "string", "null" ], "description": "Name of the parent harness this example inherits from when adopted\n(e.g. `generic`). Resolved per-org at import time — no UUIDs are\nhardcoded." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorization." } } }, "HarnessPreviewResponse": { "type": "object", "description": "Preview response showing merged prompt and tools", "required": [ "system_prompt", "tools" ], "properties": { "system_prompt": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object" } } } }, "HarnessStatus": { "type": "string", "description": "Harness lifecycle status.\n- `active`: Harness is available for use\n- `archived`: Harness is hidden from listings and cannot be modified or assigned\n- `deleted`: Harness is a tombstone kept only for historical references", "enum": [ "active", "archived", "deleted" ], "example": "active" }, "HealthCheckCaseResult": { "type": "object", "description": "Outcome of a single case after the agent ran and was scored.", "required": [ "name", "user_message", "rubric", "passed", "score", "judge_reason", "deterministic_reason", "turns", "latency_ms" ], "properties": { "deterministic_reason": { "type": "string", "description": "Deterministic-check explanation (completion, non-empty, turn bound)." }, "error": { "type": [ "string", "null" ], "description": "Set when the case errored or timed out instead of completing." }, "input_tokens": { "type": "integer", "format": "int32", "description": "Input tokens for this case: the agent session turns plus the judge call.", "minimum": 0 }, "judge_reason": { "type": "string", "description": "LLM judge explanation." }, "latency_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "name": { "type": "string" }, "output_tokens": { "type": "integer", "format": "int32", "description": "Output tokens for this case: the agent session turns plus the judge call.", "minimum": 0 }, "passed": { "type": "boolean", "description": "True only when both the deterministic checks and the LLM judge pass." }, "rubric": { "type": "string" }, "score": { "type": "number", "format": "double", "description": "LLM judge score, 0.0–1.0." }, "session_id": { "type": [ "string", "null" ], "description": "Public ID of the real session created for this case (browsable in UI)." }, "turns": { "type": "integer", "format": "int32", "minimum": 0 }, "user_message": { "type": "string" } } }, "HealthCheckRun": { "type": "object", "description": "API view of a health check run.", "required": [ "id", "config_hash", "status", "created_at" ], "properties": { "agent_id": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "config_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "id": { "type": "string", "description": "Public ID (`healthcheck_…`)." }, "model_id": { "type": [ "string", "null" ] }, "results": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/HealthCheckCaseResult" }, "description": "Per-case results (present once the run has produced any)." }, "status": { "$ref": "#/components/schemas/HealthCheckStatus" }, "summary": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HealthCheckSummary" } ] } } }, "HealthCheckStatus": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "HealthCheckSummary": { "type": "object", "description": "Aggregate metrics across all cases in a run.", "required": [ "total", "passed", "failed", "errored", "pass_rate", "avg_score", "avg_turns", "total_input_tokens", "total_output_tokens" ], "properties": { "avg_score": { "type": "number", "format": "double" }, "avg_turns": { "type": "number", "format": "double" }, "errored": { "type": "integer", "format": "int32", "minimum": 0 }, "failed": { "type": "integer", "format": "int32", "minimum": 0 }, "pass_rate": { "type": "number", "format": "double" }, "passed": { "type": "integer", "format": "int32", "minimum": 0 }, "total": { "type": "integer", "format": "int32", "minimum": 0 }, "total_input_tokens": { "type": "integer", "format": "int64", "minimum": 0 }, "total_output_tokens": { "type": "integer", "format": "int64", "minimum": 0 } } }, "HealthResponse": { "type": "object", "description": "System health response", "required": [ "status", "total_workers", "active_workers", "workers_accepting", "total_capacity", "current_load", "load_percentage", "pending_tasks", "claimed_tasks", "completed_tasks", "failed_tasks", "started_tasks", "running_workflows", "pending_workflows", "completed_workflows", "failed_workflows", "started_workflows", "dlq_size" ], "properties": { "active_workers": { "type": "integer", "description": "Number of workers in the `running` state, ready to claim tasks.", "example": 4, "minimum": 0 }, "claimed_tasks": { "type": "integer", "description": "Tasks currently claimed by a worker (gauge).", "example": 7, "minimum": 0 }, "completed_tasks": { "type": "integer", "description": "Cumulative count of tasks that completed successfully (monotonic counter).", "example": 12041, "minimum": 0 }, "completed_workflows": { "type": "integer", "description": "Cumulative count of workflows that completed successfully (monotonic counter).", "example": 4128, "minimum": 0 }, "current_load": { "type": "integer", "description": "Total tasks currently in flight across all workers.", "example": 7, "minimum": 0 }, "dlq_size": { "type": "integer", "description": "Size of the dead-letter queue (gauge). High values indicate stuck activities.", "example": 0, "minimum": 0 }, "event_delivery": { "type": [ "string", "null" ], "description": "Event-delivery backend in use: `nats` for distributed deployments, `in_memory` for single-instance. `None` if the field was omitted by an older server.", "example": "nats" }, "failed_tasks": { "type": "integer", "description": "Cumulative count of tasks that failed terminally or were sent to the DLQ (monotonic counter).", "example": 34, "minimum": 0 }, "failed_workflows": { "type": "integer", "description": "Cumulative count of workflows that ended in failure (monotonic counter).", "example": 12, "minimum": 0 }, "load_percentage": { "type": "number", "format": "double", "description": "`current_load / total_capacity * 100`. 0.0 when no workers are registered.", "example": 21.875 }, "pending_tasks": { "type": "integer", "description": "Tasks waiting to be claimed (gauge).", "example": 2, "minimum": 0 }, "pending_workflows": { "type": "integer", "description": "Workflows waiting to be claimed (gauge).", "example": 1, "minimum": 0 }, "running_workflows": { "type": "integer", "description": "Workflows currently executing (gauge).", "example": 3, "minimum": 0 }, "started_tasks": { "type": "integer", "description": "Cumulative count of tasks claimed at least once (monotonic counter).", "example": 12082, "minimum": 0 }, "started_workflows": { "type": "integer", "description": "Cumulative count of workflows that started (monotonic counter).", "example": 4144, "minimum": 0 }, "status": { "type": "string", "description": "Aggregate system status: `healthy`, `degraded`, or `unhealthy`. Derived from worker availability, load, and queue depths.", "example": "healthy" }, "total_capacity": { "type": "integer", "description": "Sum of `max_concurrency` across all workers (the upper bound on concurrent task execution).", "example": 32, "minimum": 0 }, "total_workers": { "type": "integer", "description": "Total number of workers registered (heartbeating in the last window).", "example": 4, "minimum": 0 }, "workers_accepting": { "type": "integer", "description": "Number of workers currently accepting new task assignments (subset of `active_workers`; drains/backpressure excluded).", "example": 4, "minimum": 0 } } }, "ImageContentPart": { "type": "object", "description": "Image content part (base64 or URL)", "properties": { "base64": { "type": [ "string", "null" ] }, "media_type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "ImageFileContentPart": { "type": "object", "description": "Image file content part (reference to uploaded image)\n\nThis is used for images uploaded via the /images API.\nThe image data is stored separately and referenced by ID.\nNote: Currently filtered out before sending to LLM.", "required": [ "image_id" ], "properties": { "filename": { "type": [ "string", "null" ], "description": "Original filename (for display)" }, "image_id": { "type": "string", "description": "ID of the uploaded image (format: img_{32-hex})", "example": "img_01933b5a00007000800000000000001" } } }, "ImageInfo": { "type": "object", "description": "Image metadata (without binary data)", "required": [ "id", "filename", "content_type", "size_bytes", "metadata", "created_at" ], "properties": { "content_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "filename": { "type": "string" }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "img_01933b5a00007000800000000000001" }, "metadata": { "description": "Free-form metadata attached to this resource." }, "size_bytes": { "type": "integer", "format": "int64" } } }, "ImageUploadResponse": { "type": "object", "description": "Image upload response", "required": [ "id", "filename", "content_type", "size_bytes", "created_at" ], "properties": { "content_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "filename": { "type": "string" }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "img_01933b5a00007000800000000000001" }, "size_bytes": { "type": "integer", "format": "int64" } } }, "ImportOkfBundleRequest": { "type": "object", "description": "Request body for `okf_import`.", "properties": { "bundle_base64": { "type": [ "string", "null" ], "description": "A base64-encoded `.tar.gz` OKF bundle. Mutually exclusive with `files`." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/OkfFileInput" }, "description": "Inline bundle files. Mutually exclusive with `bundle_base64`." }, "prune": { "type": "boolean", "description": "When true, delete previously-imported entries absent from this bundle." } } }, "InitialFile": { "type": "object", "description": "Starter file copied into a new session from an agent or harness.", "required": [ "path", "content" ], "properties": { "content": { "type": "string", "description": "File content: plain text or base64-encoded binary." }, "encoding": { "type": "string", "description": "Content encoding: `text` or `base64`." }, "is_readonly": { "type": "boolean", "description": "Prevent session-side edits or deletes when true." }, "path": { "type": "string", "description": "Absolute path within the session workspace. `/workspace` prefix is accepted." } } }, "InputContentPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextContentPart", "description": "Text content" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } } ], "description": "Text content" }, { "allOf": [ { "$ref": "#/components/schemas/ImageContentPart", "description": "Image content (base64 or URL)" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image" ] } } } ], "description": "Image content (base64 or URL)" }, { "allOf": [ { "$ref": "#/components/schemas/ImageFileContentPart", "description": "Image file content (reference to uploaded image by ID)" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_file" ] } } } ], "description": "Image file content (reference to uploaded image by ID)" }, { "allOf": [ { "$ref": "#/components/schemas/FileContentPart", "description": "File content (reference to uploaded file, e.g. PDF, by ID)" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file" ] } } } ], "description": "File content (reference to uploaded file, e.g. PDF, by ID)" } ], "description": "Input content part - text, image, and image_file (for user input)\n\nThis is a subset of ContentPart that users can send.\nTool calls and results are system-generated." }, "InputMessage": { "type": "object", "description": "Input message for creating a user message\n\nOnly user messages can be created via the API.\nAgent messages are created internally by the workflow.", "required": [ "content" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/InputContentPart" }, "description": "Array of content parts (text and image only)" }, "role": { "$ref": "#/components/schemas/MessageRole", "description": "Message role (always \"user\" for API-created messages)" } }, "example": { "content": [ { "text": "Why is the build failing on main?", "type": "text" } ], "role": "user" } }, "InputMessageData": { "type": "object", "description": "Data for input.message event", "required": [ "message" ], "properties": { "message": { "$ref": "#/components/schemas/RuntimeMessage", "description": "The user message" } } }, "InstallPluginRequest": { "type": "object", "description": "Request body for installing a plugin from a marketplace catalog entry.", "required": [ "marketplace_id", "plugin_name" ], "properties": { "marketplace_id": { "type": "string", "description": "Public ID of the marketplace to install from.", "example": "plgmkt_01933b5a000070008000000000000001" }, "plugin_name": { "type": "string", "description": "Name of the plugin entry in the marketplace catalog.", "example": "microsoft-docs" } } }, "KeyValueInfo": { "type": "object", "description": "Key-value entry info (key and timestamps, no value)", "required": [ "key", "value", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "description": "When the key was created" }, "key": { "type": "string", "description": "The key name" }, "updated_at": { "type": "string", "description": "When the key was last updated" }, "value": { "type": "string", "description": "The stored value" } } }, "KnowledgeBaseResponse": { "type": "object", "description": "Response body for knowledge base.", "required": [ "id", "name", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was archived, if any (RFC 3339)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was soft-deleted, if any (RFC 3339)." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages." }, "embedding_model_id": { "type": [ "string", "null" ], "description": "Optional embedding model for hybrid retrieval. `null` = keyword search only." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "kb_01933b5a000070008000000000000001" }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "status": { "type": "string", "description": "Current lifecycle status." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "KnowledgeEntryResponse": { "type": "object", "description": "Response body for knowledge entry.", "required": [ "id", "kb_id", "title", "body", "kind", "tags", "created_at", "updated_at" ], "properties": { "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "kbe_01933b5a000070008000000000000001" }, "kb_id": { "type": "string", "description": "Knowledge base's prefixed public identifier.", "example": "kb_01933b5a000070008000000000000001" }, "kind": { "type": "string", "description": "Discriminator selecting the variant of this resource." }, "resource": { "type": [ "string", "null" ], "description": "Optional OKF resource URI identifying the underlying asset.", "example": "https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached to this resource." }, "title": { "type": "string", "description": "Human-readable title. Safe to render in user-facing messages." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "KnowledgeIndexDocumentResponse": { "type": "object", "description": "Response body for a knowledge index document.", "required": [ "id", "index_id", "source_uri", "chunk_count", "created_at", "updated_at" ], "properties": { "chunk_count": { "type": "integer", "format": "int32", "description": "Denormalized chunk count for this document." }, "content_hash": { "type": [ "string", "null" ], "description": "Content hash driving incremental re-embedding." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "kidoc_01933b5a000070008000000000000001" }, "index_id": { "type": "string", "description": "Parent index's prefixed public identifier.", "example": "kidx_01933b5a000070008000000000000001" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp this document was last seen during a sync pass (RFC 3339)." }, "mime_type": { "type": [ "string", "null" ], "description": "Document MIME type, if known." }, "size_bytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Document size in bytes, if known." }, "source_uri": { "type": "string", "description": "Stable per-source locator (e.g. `github://owner/repo@main/docs/x.md`)." }, "title": { "type": [ "string", "null" ], "description": "Document title, if known." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "KnowledgeIndexResponse": { "type": "object", "description": "Response body for a knowledge index.", "required": [ "id", "name", "source_type", "source_config", "embedding_model_id", "document_count", "status", "sync_status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was archived, if any (RFC 3339)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was soft-deleted, if any (RFC 3339)." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages." }, "document_count": { "type": "integer", "description": "Number of documents currently retained by this index.", "minimum": 0 }, "embedding_model_id": { "type": "string", "description": "Embedding model used to embed chunks. Required." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "kidx_01933b5a000070008000000000000001" }, "last_sync_error": { "type": [ "string", "null" ], "description": "Sanitized failure reason from the last failed sync, if any." }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last successful sync, if any (RFC 3339)." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "source_config": { "description": "Non-secret source coordinates. Never holds credentials." }, "source_type": { "type": "string", "description": "External source type. One of `github`, `git`." }, "status": { "type": "string", "description": "Current lifecycle status." }, "sync_status": { "type": "string", "description": "Syncout pipeline state. One of `idle`, `pending`, `syncing`, `synced`, `failed`." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." }, "vector_dim": { "type": [ "integer", "null" ], "format": "int32", "description": "Embedding dimension, recorded on first successful sync." } } }, "LatestHealthCheckRun": { "type": "object", "description": "The most recent health-check run for an agent, paired with whether the\nagent's current resolved config differs from the config that run was\nexecuted against. Returned by the latest-run endpoint so the agent editor\ncan show prior results on mount without triggering a new run, and surface a\n\"config changed since last run\" hint. See knowledge/evaluation/agent-checks.md and EVE-588.", "required": [ "config_changed" ], "properties": { "config_changed": { "type": "boolean", "description": "True when `run` exists but was executed against a different resolved\nconfig than the agent currently has (UI shows a re-run hint)." }, "run": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HealthCheckRun", "description": "The latest run, or `None` if the agent has never been health-checked." } ] } } }, "LeasedResource": { "type": "object", "description": "A lifecycle-managed external resource owned by a session-capable workflow.", "required": [ "id", "provider", "resource_type", "external_id", "status", "lease_duration_seconds", "last_touched_at", "lease_expires_at", "cleanup_attempts", "created_at", "updated_at" ], "properties": { "cleanup_attempts": { "type": "integer", "format": "int32", "description": "Number of cleanup attempts so far.", "example": 0, "minimum": 0 }, "cleanup_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Cleanup completion time for released resources.", "example": "2026-05-25T10:30:04Z" }, "cleanup_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Cleanup attempt start time when the resource is currently claimed.", "example": "2026-05-25T10:30:00Z" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this leased resource was created (RFC 3339).", "example": "2026-05-25T10:00:00Z" }, "display_name": { "type": [ "string", "null" ], "description": "Optional user-facing label.", "example": "Customer 42 — Q3 brief" }, "external_id": { "type": "string", "description": "Stable provider identifier for cleanup calls.", "example": "sbx_a3f1c9d2e8" }, "id": { "type": "string", "description": "Unique identifier (format: resource_{32-hex}).", "example": "resource_01933b5a00007000800000000000001" }, "last_cleanup_error": { "type": [ "string", "null" ], "description": "Last cleanup error message, if any.", "example": "daytona.api.timeout: provider call exceeded 10s" }, "last_touched_at": { "type": "string", "format": "date-time", "description": "Last successful touch from tool activity.", "example": "2026-05-25T10:14:00Z" }, "lease_duration_seconds": { "type": "integer", "format": "int32", "description": "Lease duration used when refreshing the lease.", "example": 900, "minimum": 0 }, "lease_expires_at": { "type": "string", "format": "date-time", "description": "Absolute deadline after which cleanup becomes due.", "example": "2026-05-25T10:29:00Z" }, "metadata": { "type": "object", "description": "Provider-specific non-secret metadata for UI/debugging. Free-form JSON\nobject — shape is provider-defined.\nExample: `{\"region\": \"us-west-2\", \"snapshot_id\": \"snap_42\"}`.\nTHREAT[TM-API-015]: This field is returned by the session resources API\nand rendered in the UI, so providers must never persist bearer tokens or\nother secrets here." }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "User connection owner used for provider cleanup, if known.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "provider": { "type": "string", "description": "External provider responsible for the resource (e.g. \"daytona\").", "example": "daytona" }, "resource_type": { "type": "string", "description": "Provider-specific resource type (e.g. \"sandbox\", \"browser_session\").", "example": "sandbox" }, "session_id": { "type": [ "string", "null" ], "description": "Session that currently owns the resource, if still attached.", "example": "session_01933b5a00007000800000000000001" }, "status": { "$ref": "#/components/schemas/LeasedResourceStatus", "description": "Current lifecycle status." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this leased resource was last updated (RFC 3339).", "example": "2026-05-25T10:14:00Z" } } }, "LeasedResourceStatus": { "type": "string", "description": "Runtime status for a leased resource.", "enum": [ "active", "cleaning", "released", "cleanup_failed" ] }, "LedgerEntry": { "type": "object", "description": "Immutable platform ledger record for resource consumption or credit.", "required": [ "id", "budget_id", "amount", "meter_source", "created_at" ], "properties": { "amount": { "type": "number", "format": "double", "description": "Positive = debit (consumption), negative = credit (top-up/refund)." }, "budget_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "meter_source": { "type": "string", "description": "Which meter produced this: \"llm_tokens\", \"tool_calls\", etc." }, "ref_id": { "type": [ "string", "null" ], "description": "Reference entity ID." }, "ref_type": { "type": [ "string", "null" ], "description": "Reference entity type: \"llm_generation\", \"tool_execution\", \"manual\"." }, "session_id": { "type": [ "string", "null" ], "description": "Session context for this entry." } } }, "ListExecutionsQuery": { "type": "object", "description": "Query parameters for listing executions of a schedule — optional status\nfilter plus offset/limit paging.", "properties": { "limit": { "type": [ "integer", "null" ], "format": "int32", "description": "Pagination limit (default: 20, max: 100)", "example": 20, "minimum": 0 }, "offset": { "type": [ "integer", "null" ], "format": "int32", "description": "Pagination offset", "example": 0, "minimum": 0 }, "status": { "type": [ "string", "null" ], "description": "Filter by execution status", "example": "completed" } } }, "ListKnowledgeBasesQuery": { "type": "object", "description": "Query parameters for `GET /v1/knowledge-bases` — optional name/desc\nsearch plus a flag to include archived knowledge bases.", "properties": { "include_archived": { "type": [ "boolean", "null" ], "description": "When `true`, also returns archived knowledge bases.", "example": false }, "search": { "type": [ "string", "null" ], "description": "Substring filter applied to knowledge-base name and description.", "example": "runbook" } } }, "ListKnowledgeEntriesQuery": { "type": "object", "description": "Query parameters for listing entries inside a knowledge base — optional\ntext search and tag filter.", "properties": { "kind": { "type": [ "string", "null" ], "description": "Discriminator selecting the variant of this resource. One of `note`,\n`table`, `business`, `query`, `runbook`.", "example": "runbook" }, "search": { "type": [ "string", "null" ], "description": "Substring filter applied to entry title and body.", "example": "refund" } } }, "ListKnowledgeIndexesQuery": { "type": "object", "description": "Query parameters for `GET /v1/knowledge-indexes` — optional name/desc\nsearch plus a flag to include archived indexes.", "properties": { "include_archived": { "type": [ "boolean", "null" ], "description": "When `true`, also returns archived knowledge indexes.", "example": false }, "search": { "type": [ "string", "null" ], "description": "Substring filter applied to index name and description.", "example": "docs" } } }, "ListMemoriesQuery": { "type": "object", "description": "Query parameters for `GET /v1/memories` — optional name search and a\nflag to include archived memories in the listing.", "properties": { "include_archived": { "type": [ "boolean", "null" ] }, "search": { "type": [ "string", "null" ] } } }, "ListResponse_Agent": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Agent configuration for agentic loop.\nAn agent defines the behavior and capabilities of an AI assistant.", "required": [ "id", "name", "system_prompt", "harness_id", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the agent was archived.", "example": "2026-05-26T00:00:00Z" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities enabled for this agent with per-agent configuration.\nCapabilities add tools and system prompt modifications." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was created.", "example": "2026-04-01T10:00:00Z" }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model ID for this agent.\nCan be overridden at the session level.", "example": "model_01933b5a00007000800000000000001" }, "default_version_id": { "type": [ "string", "null" ], "description": "Default immutable version used by deployments that choose the default policy.", "example": "agentver_01933b5a00007000800000000000001" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the agent was deleted.", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the agent does.", "example": "Handles refund and shipping questions; escalates billing disputes." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI (e.g. \"Customer Support Agent\").\nFalls back to `name` when absent.", "example": "Customer Support Agent" }, "exposed": { "type": "boolean", "description": "Whether any endpoint on this agent is currently live. Derived from the\nendpoint rows on read and never stored: a stored flag would be a second\nwriter for state the endpoints already own." }, "exposures_suspended": { "type": "boolean", "description": "Incident switch: when true, no endpoint on this agent accepts traffic\n(EVE-1007). Distinct from archiving — it leaves per-endpoint status\nuntouched so clearing it restores exactly the previously live set." }, "forked_from_agent_id": { "type": [ "string", "null" ], "description": "Source agent for a forked agent.", "example": "agent_01933b5a00007000800000000000001" }, "forked_from_version_id": { "type": [ "string", "null" ], "description": "Source version for a forked agent.", "example": "agentver_01933b5a00007000800000000000001" }, "harness_id": { "type": "string", "description": "Harness that supplies the base execution environment for this agent.", "example": "harness_01933b5a00007000800000000000001" }, "id": { "type": "string", "description": "External identifier (agent_<32-hex>). Shown as \"id\" in API.\nClient-supplied or auto-generated.", "example": "agent_01933b5a000070008000000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this agent." }, "intro_markdown": { "type": [ "string", "null" ], "description": "Optional Markdown intro rendered as an intro box at the top of a fresh\nPlatform Chat thread. Images are allowed. Wins over the harness intro.\nHidden once the user inputs.", "example": "Hey, I'm Ava. Ask me anything about your account." }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this agent.", "example": 50, "minimum": 0 }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this agent and inherited by its sessions." }, "name": { "type": "string", "description": "Name, unique per org (e.g. \"customer-support\").", "example": "customer-support" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs agent sessions can reach.\nMerged with harness and session layers (allowed: intersect, blocked: union)." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "root_agent_id": { "type": [ "string", "null" ], "description": "Root agent lineage identifier for grouping fork families.", "example": "agent_01933b5a00007000800000000000001" }, "short_description": { "type": [ "string", "null" ], "description": "Optional one-line description in simplified Markdown, shown below the\nchat title once the intro is hidden. Wins over the harness value.", "example": "Answers account questions in seconds." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. Win over the\nharness starters when non-empty." }, "status": { "$ref": "#/components/schemas/AgentStatus", "description": "Current lifecycle status of the agent." }, "system_prompt": { "type": "string", "description": "System prompt that defines the agent's behavior.\nSent as the first message in every conversation.", "example": "You are a friendly customer support agent for Acme Corp. Verify orders before issuing refunds. Escalate any billing disputes to a human." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering agents.", "example": [ "support", "production" ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools registered for this agent.\nThese tools are executed by the client, not the server." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was last updated.", "example": "2026-05-20T14:00:00Z" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative token usage across all sessions for this agent." } ] } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_AgentCredentialBinding": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Metadata for a write-only credential bound to one agent and MCP tool parameter.", "required": [ "id", "agent_id", "mcp_server_name", "mcp_server_url", "tool_name", "parameter_name", "label", "configured", "created_at", "updated_at", "setup_url" ], "properties": { "agent_id": { "type": "string", "description": "Agent that exclusively owns and may use this credential.", "example": "agent_01933b5a000070008000000000000001" }, "configured": { "type": "boolean", "description": "Whether an encrypted value has been provisioned.", "example": true }, "created_at": { "type": "string", "description": "RFC 3339 creation time.", "example": "2026-08-08T16:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Optional explanation of why the credential is needed.", "example": "Delivers scheduled status notifications" }, "id": { "type": "string", "format": "uuid", "description": "Stable credential binding identifier.", "example": "01933b5a-0000-7000-8000-000000000001" }, "label": { "type": "string", "description": "Human-readable credential label.", "example": "Visti channel key" }, "mcp_server_name": { "type": "string", "description": "Name of the attached MCP server.", "example": "visti" }, "mcp_server_url": { "type": "string", "description": "Exact MCP endpoint authorized to receive the credential.", "example": "https://visti.sh/mcp" }, "parameter_name": { "type": "string", "description": "Top-level tool argument injected by the server.", "example": "channel_key" }, "setup_url": { "type": "string", "description": "Relative UI route where the user can securely provision the value.", "example": "/agents/agent_01933b5a000070008000000000000001?tab=credentials" }, "tool_name": { "type": "string", "description": "MCP tool whose outbound call receives the credential.", "example": "visti_send" }, "updated_at": { "type": "string", "description": "RFC 3339 last-update time.", "example": "2026-08-08T16:05:00Z" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_CapabilityInfo": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Public capability information (without internal details)\nThis is what gets returned from the API\nNamed CapabilityInfo to distinguish from the Capability trait", "required": [ "id", "name", "description", "status" ], "properties": { "agent_count": { "type": "integer", "format": "int64", "description": "Number of active agents referencing this capability in the org.", "example": 42, "minimum": 0 }, "category": { "type": [ "string", "null" ], "description": "Category for grouping in UI", "example": "filesystem" }, "config_schema": { "type": "object", "description": "JSON Schema for capability-specific per-agent config." }, "config_ui_schema": { "type": "object", "description": "react-jsonschema-form uiSchema hints for rendering config_schema." }, "dependencies": { "type": "array", "items": { "type": "string" }, "description": "IDs of capabilities that this capability depends on.\nWhen this capability is selected, its dependencies are automatically included.", "example": [ "approval" ] }, "description": { "type": "string", "description": "Description of what this capability provides", "example": "Read, write, edit, list, grep, delete, and stat files in the session workspace." }, "docs_slug": { "type": [ "string", "null" ], "description": "Slug under https://dev.everruns.com/capabilities/ when public docs exist.", "example": "session_file_system" }, "features": { "type": "array", "items": { "type": "string" }, "description": "UI feature strings this capability contributes to.\nMultiple capabilities can contribute the same feature.", "example": [ "file_browser" ] }, "harness_count": { "type": "integer", "format": "int64", "description": "Number of active harnesses referencing this capability in the org.", "example": 7, "minimum": 0 }, "icon": { "type": [ "string", "null" ], "description": "Icon name (for UI rendering)", "example": "Folder" }, "id": { "type": "string", "description": "Unique capability identifier", "example": "session_file_system" }, "is_guardrail": { "type": "boolean", "description": "Whether this capability is a guardrail (constrains agent behavior\nrather than granting abilities). Used for UI grouping and filtering.", "example": false }, "is_mcp": { "type": "boolean", "description": "Whether this is an MCP server capability (for UI badge)", "example": false }, "is_skill": { "type": "boolean", "description": "Whether this is an Agent Skill capability (for UI badge)", "example": false }, "localizations": { "type": "object", "description": "Localized display strings keyed by lowercase language tag (e.g. \"uk\").\nThe \"en\" entry carries only `config_description`, since the base\nname/description/config_schema strings are already English.", "additionalProperties": { "$ref": "#/components/schemas/CapabilityLocalizationInfo" }, "propertyNames": { "type": "string" }, "example": { "uk": { "description": "Монтує спільні файли пам'яті в сесії.", "name": "Пам'ять" } } }, "name": { "type": "string", "description": "Display name", "example": "Session File System" }, "risk_level": { "$ref": "#/components/schemas/RiskLevel", "description": "TM-AGENT-005: Risk level. High-risk capabilities require admin approval." }, "status": { "type": "string", "description": "Current status", "example": "active" }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt addition contributed by this capability", "example": "You can read and write files in /workspace via the session_file_system tools." }, "tool_definitions": { "type": "array", "items": { "type": "object" }, "description": "Tool definitions provided by this capability", "example": [ { "description": "Read a file from the session workspace.", "name": "read_file" }, { "description": "Write or overwrite a file in the session workspace.", "name": "write_file" } ] } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_DatabaseInfoResponse": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Database info response.", "required": [ "name", "size_bytes", "page_count", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "description": "Timestamp when this resource was created (RFC 3339)." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "page_count": { "type": "integer", "format": "int32" }, "size_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_Event": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Standard event following the Everruns event protocol.\n\nAll events have a consistent structure:\n- `id`: Unique event identifier (format: event_{32-hex})\n- `type`: Event type in dot notation (e.g., \"input.message\", \"reason.started\")\n- `ts`: ISO 8601 timestamp with millisecond precision\n- `session_id`: Session this event belongs to (format: session_{32-hex})\n- `context`: Correlation context for tracing\n- `data`: Event-specific payload (typed via EventData enum)\n- `metadata`: Optional arbitrary metadata\n- `tags`: Optional list of tags for filtering", "required": [ "id", "type", "ts", "session_id", "context", "data" ], "properties": { "context": { "$ref": "#/components/schemas/EventContext", "description": "Correlation context" }, "data": { "$ref": "#/components/schemas/EventData", "description": "Event-specific payload. The schema depends on the event type.\nSee EventData documentation for the mapping of type to data schema." }, "id": { "type": "string", "description": "Unique event identifier (format: event_{32-hex})", "example": "event_01933b5a00007000800000000000001" }, "metadata": { "description": "Arbitrary metadata for the event" }, "sequence": { "type": [ "integer", "null" ], "format": "int32", "description": "Sequence number within session (for ordering)" }, "session_id": { "type": "string", "description": "Session this event belongs to (format: session_{32-hex})", "example": "session_01933b5a00007000800000000000001" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tags for filtering and categorization" }, "ts": { "type": "string", "format": "date-time", "description": "Event timestamp" }, "type": { "type": "string", "description": "Event type in dot notation" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_FileInfo": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "File metadata without content", "required": [ "id", "session_id", "path", "name", "is_directory", "is_readonly", "size_bytes", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this entry was created (RFC 3339).", "example": "2026-05-25T10:14:00Z" }, "id": { "type": "string", "format": "uuid", "description": "Internal database UUID for this file entry.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "is_directory": { "type": "boolean", "description": "`true` when this entry represents a directory; `false` for a regular file.", "example": false }, "is_readonly": { "type": "boolean", "description": "Whether the entry was marked read-only at creation. Read-only entries cannot be edited or deleted by the session.", "example": false }, "name": { "type": "string", "description": "File or directory name (the last segment of `path`).", "example": "notes.md" }, "path": { "type": "string", "description": "Absolute path within the session workspace (e.g. `/notes.md`).", "example": "/notes.md" }, "session_id": { "type": "string", "format": "uuid", "description": "UUID of the owning session.", "example": "01933b5a-0000-7000-8000-000000000001" }, "size_bytes": { "type": "integer", "format": "int64", "description": "File size in bytes. `0` for directories.", "example": 4096 }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this entry was last updated (RFC 3339).", "example": "2026-05-25T10:15:30Z" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_GrepResult": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Grep result for a file", "required": [ "path", "matches" ], "properties": { "matches": { "type": "array", "items": { "$ref": "#/components/schemas/GrepMatch" } }, "path": { "type": "string" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_Harness": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Harness configuration for sessions.\nA harness defines the base behavior and capabilities that apply to all sessions.", "required": [ "id", "name", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was archived.", "example": "2026-05-26T00:00:00Z" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities enabled for this harness with per-harness configuration." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was created.", "example": "2026-04-01T10:00:00Z" }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model ID for this harness.\nLowest priority in chain: controls > session > agent > harness.", "example": "model_01933b5a00007000800000000000001" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was deleted.", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the harness does.", "example": "Default harness with file-system + secrets capabilities; safe baseline for new agents." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI.", "example": "Generic Harness" }, "embedder_metadata": { "type": "object", "description": "Arbitrary key-value metadata injected into LLM requests for observability.\nKeys from system context (session_id, org_id, etc.) always take precedence.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": { "env": "production", "team": "platform" } }, "icon": { "type": [ "string", "null" ], "description": "Display glyph name rendered by the UI (e.g. \"message-circle\").\n\nBuilt-in harnesses declare it in their definition; custom harnesses\nleave it unset and fall back to the UI's generic harness glyph.", "example": "message-circle" }, "id": { "type": "string", "description": "Unique identifier for the harness (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this harness." }, "intro_markdown": { "type": [ "string", "null" ], "description": "Optional Markdown intro rendered as an intro box at the top of a fresh\nPlatform Chat thread. Images are allowed. The agent intro wins over\nthe harness intro. Hidden once the user inputs.", "example": "I can triage incidents, dig through logs, and draft the update." }, "is_built_in": { "type": "boolean", "description": "Whether this harness is built-in (system-managed, readonly).\nBuilt-in harnesses are provisioned during org initialization and\ncannot be modified or deleted via the API. Users can copy them.", "example": false }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this harness and inherited by descendant layers." }, "name": { "type": "string", "description": "Name, unique per org (e.g. \"generic\").", "example": "generic" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs sessions can reach.\nMerged with agent and session layers (allowed: intersect, blocked: union)." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "parent_harness_id": { "type": [ "string", "null" ], "description": "Optional parent harness that this harness inherits from.", "example": "harness_01933b5a000070008000000000000602" }, "short_description": { "type": [ "string", "null" ], "description": "Optional one-line description in simplified Markdown, shown below the\nchat title once the intro is hidden. The agent value wins.", "example": "Knows your agents, harnesses, models, and runs." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. The agent's\nstarters win when non-empty, otherwise the harness's apply." }, "status": { "$ref": "#/components/schemas/HarnessStatus", "description": "Current lifecycle status of the harness." }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt that defines the harness's base behavior.\n\nForms the foundation of the prompt stack. Optional: when absent the\nharness contributes no base prompt, so the effective prompt comes\nentirely from the parent harness (if any), the agent, the session, and\ncapability contributions. Empty/whitespace-only values normalize to\n`None`.", "example": "You are an Everruns agent. Be concise, cite sources when possible, and decline tasks outside your assigned scope." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering harnesses.", "example": [ "baseline", "production" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was last updated.", "example": "2026-05-20T14:00:00Z" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_KeyValueInfo": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Key-value entry info (key and timestamps, no value)", "required": [ "key", "value", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "description": "When the key was created" }, "key": { "type": "string", "description": "The key name" }, "updated_at": { "type": "string", "description": "When the key was last updated" }, "value": { "type": "string", "description": "The stored value" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_KnowledgeBaseResponse": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response body for knowledge base.", "required": [ "id", "name", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was archived, if any (RFC 3339)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was soft-deleted, if any (RFC 3339)." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages." }, "embedding_model_id": { "type": [ "string", "null" ], "description": "Optional embedding model for hybrid retrieval. `null` = keyword search only." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "kb_01933b5a000070008000000000000001" }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "status": { "type": "string", "description": "Current lifecycle status." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_KnowledgeEntryResponse": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response body for knowledge entry.", "required": [ "id", "kb_id", "title", "body", "kind", "tags", "created_at", "updated_at" ], "properties": { "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "kbe_01933b5a000070008000000000000001" }, "kb_id": { "type": "string", "description": "Knowledge base's prefixed public identifier.", "example": "kb_01933b5a000070008000000000000001" }, "kind": { "type": "string", "description": "Discriminator selecting the variant of this resource." }, "resource": { "type": [ "string", "null" ], "description": "Optional OKF resource URI identifying the underlying asset.", "example": "https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached to this resource." }, "title": { "type": "string", "description": "Human-readable title. Safe to render in user-facing messages." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_KnowledgeIndexDocumentResponse": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response body for a knowledge index document.", "required": [ "id", "index_id", "source_uri", "chunk_count", "created_at", "updated_at" ], "properties": { "chunk_count": { "type": "integer", "format": "int32", "description": "Denormalized chunk count for this document." }, "content_hash": { "type": [ "string", "null" ], "description": "Content hash driving incremental re-embedding." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "kidoc_01933b5a000070008000000000000001" }, "index_id": { "type": "string", "description": "Parent index's prefixed public identifier.", "example": "kidx_01933b5a000070008000000000000001" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp this document was last seen during a sync pass (RFC 3339)." }, "mime_type": { "type": [ "string", "null" ], "description": "Document MIME type, if known." }, "size_bytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Document size in bytes, if known." }, "source_uri": { "type": "string", "description": "Stable per-source locator (e.g. `github://owner/repo@main/docs/x.md`)." }, "title": { "type": [ "string", "null" ], "description": "Document title, if known." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_KnowledgeIndexResponse": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response body for a knowledge index.", "required": [ "id", "name", "source_type", "source_config", "embedding_model_id", "document_count", "status", "sync_status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was archived, if any (RFC 3339)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was soft-deleted, if any (RFC 3339)." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages." }, "document_count": { "type": "integer", "description": "Number of documents currently retained by this index.", "minimum": 0 }, "embedding_model_id": { "type": "string", "description": "Embedding model used to embed chunks. Required." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "kidx_01933b5a000070008000000000000001" }, "last_sync_error": { "type": [ "string", "null" ], "description": "Sanitized failure reason from the last failed sync, if any." }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last successful sync, if any (RFC 3339)." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "source_config": { "description": "Non-secret source coordinates. Never holds credentials." }, "source_type": { "type": "string", "description": "External source type. One of `github`, `git`." }, "status": { "type": "string", "description": "Current lifecycle status." }, "sync_status": { "type": "string", "description": "Syncout pipeline state. One of `idle`, `pending`, `syncing`, `synced`, `failed`." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." }, "vector_dim": { "type": [ "integer", "null" ], "format": "int32", "description": "Embedding dimension, recorded on first successful sync." } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_McpServer": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "MCP Server configuration.\nRepresents a remote MCP server that can provide tools and resources.", "required": [ "id", "name", "url", "transport_type", "status", "api_key_set", "created_at", "updated_at" ], "properties": { "api_key_set": { "type": "boolean", "description": "Whether an API key has been configured." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the MCP server was archived." }, "auth_mode": { "$ref": "#/components/schemas/McpServerAuthMode", "description": "Authentication mode for this MCP server." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the MCP server was created." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the MCP server was deleted." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the MCP server.", "example": "Atlassian MCP Server for Jira and Confluence" }, "headers": { "type": "object", "description": "Additional HTTP headers for authentication.\nKeys are header names, values are header values.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Unique identifier for the MCP server.", "example": "mcp_01933b5a00007000800000000000001" }, "name": { "type": "string", "description": "Display name of the MCP server.", "example": "atlassian-mcp-server" }, "oauth_provider_id": { "type": [ "string", "null" ], "description": "Stable provider id used for user-scoped OAuth connections." }, "protocol_mode": { "$ref": "#/components/schemas/McpProtocolMode", "description": "Protocol-era adoption policy for the MCP client (`auto` negotiates)." }, "status": { "$ref": "#/components/schemas/McpServerStatus", "description": "Current lifecycle status of the MCP server." }, "transport_type": { "$ref": "#/components/schemas/McpServerTransportType", "description": "Transport type (currently only HTTP supported)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the MCP server was last updated." }, "url": { "type": "string", "description": "URL of the MCP server endpoint.", "example": "https://mcp.atlassian.com/v1/mcp" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_Memory": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response body for memory.", "required": [ "id", "name", "scope", "source_type", "source", "is_readonly", "sync_status", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was archived, if any (RFC 3339).", "example": "2026-05-26T00:00:00Z" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339).", "example": "2026-04-01T10:00:00Z" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was soft-deleted, if any (RFC 3339).", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Living design documents synced from GitHub" }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "mem_01933b5a000070008000000000000001" }, "is_readonly": { "type": "boolean", "description": "Whether the memory is mounted read-only into sessions. Read-only memories accept no writes from the session sandbox.", "example": false }, "last_sync_error": { "type": [ "string", "null" ], "description": "Most recent sync error message; cleared on the next successful sync.", "example": "ssh: connect to host github.com port 22: Connection timed out" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent successful sync (RFC 3339). `None` if never synced.", "example": "2026-05-25T08:00:00Z" }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "design-docs" }, "owner_agent_id": { "type": [ "string", "null" ], "description": "Owning agent when `scope = agent`.", "example": "agent_01933b5a000070008000000000000001" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Owning user when `scope = user`." }, "scope": { "type": "string", "description": "Ownership scope (`org`, `agent`, or `user`).", "example": "org" }, "source": { "$ref": "#/components/schemas/MemorySourceResponse", "description": "Source-specific configuration (git remote, github repo, manual upload)." }, "source_type": { "type": "string", "description": "Source kind discriminator (`manual`, `git`, `github`). Determines which `source` variant is populated.", "example": "github" }, "status": { "type": "string", "description": "Current lifecycle status.", "example": "active" }, "sync_status": { "type": "string", "description": "Current sync status (`idle`, `syncing`, `succeeded`, `failed`). Only meaningful when `source_type` is `git` or `github`.", "example": "succeeded" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339).", "example": "2026-05-25T08:00:00Z" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_MemoryFileInfo": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "path", "is_directory", "size_bytes", "created_at", "updated_at" ], "properties": { "content_hash": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "is_directory": { "type": "boolean" }, "path": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_MemoryGrepResult": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "path", "size_bytes" ], "properties": { "path": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_Message": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Message - primary conversation data (API response)", "required": [ "id", "session_id", "sequence", "role", "content", "created_at" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" }, "description": "Array of content parts.\n\nReasoning artifacts appear here as `reasoning` parts, in the order the\nprovider emitted them, with opaque replay state (signatures, encrypted\npayloads) stripped." }, "controls": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Controls", "description": "Runtime controls (model, reasoning, etc.)" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "external_actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalActor", "description": "External actor identity (for messages from external channels like Slack)" } ] }, "id": { "type": "string", "description": "Unique message ID (format: message_{32-hex})", "example": "message_01933b5a00007000800000000000001" }, "metadata": { "type": [ "object", "null" ], "description": "Message-level metadata (locale, etc.)", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExecutionPhase", "description": "Execution phase for agent messages: whether this is intermediate\n`commentary` or the turn's `final_answer`. Absent on user messages.\n\nWithout this a client cannot tell an intermediate message from the\nanswer, which is the single question most consumers of a session need\nanswered." } ] }, "phase_source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PhaseSource", "description": "Whether `phase` was reported by the provider or inferred by the runtime\nfrom tool-call presence.\n\n`derived` is a weak signal: it means only \"this message called tools\",\nso a text-only preamble is reported as `final_answer`. Clients needing a\ndependable classification should treat `derived` accordingly." } ] }, "role": { "$ref": "#/components/schemas/MessageRole" }, "sequence": { "type": "integer", "format": "int32" }, "session_id": { "type": "string", "description": "Session ID this message belongs to (format: session_{32-hex})", "example": "session_01933b5a00007000800000000000001" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_MyInvitationResponse": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "org_name", "role" ], "properties": { "id": { "type": "string" }, "org_name": { "type": "string" }, "role": { "type": "string" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_OrganizationResponse": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Response for organization operations", "required": [ "id", "name", "default_provider_per_service", "created_at", "updated_at" ], "properties": { "base_harness_id": { "type": [ "string", "null" ], "description": "Base harness used when session creation omits harness_id." }, "created_at": { "type": "string", "format": "date-time", "description": "When the organization was created" }, "default_harness_id": { "type": [ "string", "null" ], "description": "Default harness to preselect in the UI." }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model for the organization." }, "default_provider_per_service": { "type": "object", "description": "Org-level default provider per service (EVE-569), keyed by service kind.\nEmpty when no org defaults are configured.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "External identifier (org_<32-hex-chars>)" }, "name": { "type": "string", "description": "Display name" }, "onboarding_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the org's creator finished or skipped the setup wizard. `null` means\nonboarding is still incomplete, which the UI uses to resume the user at\n`/orgs/{id}/setup`. Seeded/default and externally-synced orgs are complete." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the organization was last updated" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_SavedReport": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A user-saved report definition — a named, persistable wrapper around a\n`ReportQuery` with optional dashboard placement metadata.", "required": [ "id", "name", "query", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "dashboard": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SavedReportDashboardMetadata", "description": "Optional dashboard placement metadata. `None` means the report is\n\"library-only\" and not pinned to a dashboard layout." } ] }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages." }, "id": { "type": "string", "format": "uuid", "description": "UUID of the saved report." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "query": { "$ref": "#/components/schemas/ReportQuery", "description": "The query this report executes when run or exported. Same shape as the\n`body` of `POST /v1/reports/query` — see `ReportQuery` for the field\nbreakdown." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_SecretInfo": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Secret entry info (name and timestamps only, no value)", "required": [ "name", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "description": "When the secret was created" }, "name": { "type": "string", "description": "The secret name" }, "updated_at": { "type": "string", "description": "When the secret was last updated" } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_Skill": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Skill entity (API response type)", "required": [ "id", "name", "description", "source_type", "status", "version", "created_at", "updated_at" ], "properties": { "allowed_tools": { "type": [ "string", "null" ], "description": "Comma-separated list of tool patterns this skill may invoke. `None` means inherit from the harness." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this skill was archived, if any (RFC 3339). Archived skills are hidden from default list views." }, "compatibility": { "type": [ "string", "null" ], "description": "Compatibility marker describing host-runtime requirements declared by the skill (e.g. min platform version). Informational." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this skill was created (RFC 3339)." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this skill was hard-deleted, if any (RFC 3339)." }, "description": { "type": "string", "description": "Short, agent- and user-readable summary of what the skill does and when to use it.", "example": "Extract text and tables from PDF files." }, "disable_model_invocation": { "type": "boolean", "description": "When `true`, the LLM is prevented from auto-invoking this skill; only the user can trigger it explicitly." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "skill_01933b5a00007000800000000000001" }, "license": { "type": [ "string", "null" ], "description": "License string as declared by the skill author (e.g. `MIT`, `Apache-2.0`). Informational; not enforced." }, "metadata": { "type": "object", "description": "Free-form metadata declared by the skill author.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Stable kebab-case slug used to invoke the skill (e.g. `/pdf-processing` in chat). Safe to render in user-facing messages.", "example": "pdf-processing" }, "source_type": { "$ref": "#/components/schemas/SkillSourceType", "description": "How the skill content is sourced (filesystem, URL, embedded). Determines reload semantics." }, "status": { "$ref": "#/components/schemas/SkillStatus", "description": "Current lifecycle status (`active`, `archived`, `deleted`)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this skill was last updated (RFC 3339)." }, "user_invocable": { "type": "boolean", "description": "Whether this skill appears as a `/`-prefixed slash command for end users in chat UIs." }, "version": { "type": "string", "description": "Semver string declared by the skill author. Free-form; sorted lexicographically when comparing." } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_TaskWebhookResponse": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A configured outbound webhook target.", "required": [ "id", "url", "enabled", "has_secret", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean", "description": "Whether this webhook is enabled." }, "has_secret": { "type": "boolean", "description": "Whether a signing secret is configured (the secret itself is never returned)." }, "id": { "type": "string", "description": "Public identifier (wh_<32-hex-chars>)." }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "description": "Target URL that receives POST requests." } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_User": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "User response for listing", "required": [ "id", "email", "name", "roles", "created_at" ], "properties": { "auth_provider": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "email": { "type": "string" }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "roles": { "type": "array", "items": { "type": "string" } } } }, "description": "Array of items returned by the list operation." } } }, "ListResponse_WithUrls_App": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "App configuration for deploying agents to channels.\nAn app binds a harness and optional agent to distribution channels with a\npublish lifecycle.", "required": [ "id", "name", "harness_id", "owner_principal_id", "status", "created_at", "updated_at" ], "properties": { "agent_id": { "type": [ "string", "null" ], "description": "Optional ID of the agent to use (format: agent_{32-hex}).", "example": "agent_01933b5a00007000800000000000001" }, "agent_identity_id": { "type": [ "string", "null" ], "description": "Optional virtual identity that represents the app in unattended/channel execution.", "example": "identity_01933b5a00007000800000000000001" }, "agent_version_id": { "type": [ "string", "null" ], "description": "Pinned agent version. Required when policy is `pinned`.", "example": "agentver_01933b5a00007000800000000000001" }, "agent_version_policy": { "$ref": "#/components/schemas/AgentVersionPolicy", "description": "Version resolution policy for the optional agent." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the app was archived." }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/AppChannel" }, "description": "Distribution channels attached to this app." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the app was created." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the app was deleted." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the app does." }, "effective_owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Effective human owner summary." } ] }, "harness_id": { "type": "string", "description": "ID of the harness to use (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "id": { "type": "string", "description": "External identifier (app_<32-hex>). Shown as \"id\" in API.", "example": "app_01933b5a000070008000000000000001" }, "name": { "type": "string", "description": "Display name of the app." }, "owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Owning principal summary." } ] }, "owner_principal_id": { "type": "string", "description": "Owning principal for this app.", "example": "principal_01933b5a000070008000000000000001" }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the app was last published." }, "resolved_owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Denormalized effective human owner of the owning principal lineage." }, "status": { "$ref": "#/components/schemas/AppStatus", "description": "Current lifecycle status." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the app was last updated." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." } } }, "ListResponse_WithUrls_DeclarativeCapability": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Persisted, org-scoped declarative capability — a YAML/JSON-defined\nbundle of skills, files, and tool defs that an agent or harness can\nreference by `capability_id` or name.", "required": [ "id", "capability_id", "name", "description", "status", "definition", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was archived, if any (RFC 3339)." }, "capability_id": { "type": "string", "description": "Runtime capability reference. Agents and harnesses may use this or the plain unique name.", "example": "declarative:research_pack" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "definition": { "type": "object", "description": "Declarative capability payload: system prompt, skills, starter files, MCP servers, and metadata." }, "definition_error": { "type": [ "string", "null" ], "description": "Why the stored definition could not be parsed, when it could not be.\n\nPresent only for a corrupt row. The capability keeps its identity\ncolumns so a surface can name what is broken, but `definition` is the\ninert default and `definition.status` reports `retired`, so nothing\nreads it as a usable capability.", "example": "missing field `acts_as` at line 1 column 84" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was soft-deleted, if any (RFC 3339)." }, "description": { "type": "string", "description": "Short summary shown in pickers, search results, and API listings.", "example": "Adds research instructions, starter files, and MCP tools." }, "display_name": { "type": [ "string", "null" ], "description": "Human-facing label shown in the UI. Defaults to `name` when omitted.", "example": "Research Pack" }, "id": { "type": "string", "description": "Public resource ID for this persisted declarative capability.", "example": "cap_01933b5a000070008000000000000001" }, "name": { "type": "string", "description": "Stable unique name used in capability refs. Lowercase letters, numbers, and underscores.", "example": "research_pack" }, "status": { "type": "string", "description": "Lifecycle state for the resource: active, disabled, archived, or deleted.", "example": "active" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." } } }, "ListResponse_WithUrls_McpServer": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "MCP Server configuration.\nRepresents a remote MCP server that can provide tools and resources.", "required": [ "id", "name", "url", "transport_type", "status", "api_key_set", "created_at", "updated_at" ], "properties": { "api_key_set": { "type": "boolean", "description": "Whether an API key has been configured." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the MCP server was archived." }, "auth_mode": { "$ref": "#/components/schemas/McpServerAuthMode", "description": "Authentication mode for this MCP server." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the MCP server was created." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the MCP server was deleted." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the MCP server.", "example": "Atlassian MCP Server for Jira and Confluence" }, "headers": { "type": "object", "description": "Additional HTTP headers for authentication.\nKeys are header names, values are header values.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Unique identifier for the MCP server.", "example": "mcp_01933b5a00007000800000000000001" }, "name": { "type": "string", "description": "Display name of the MCP server.", "example": "atlassian-mcp-server" }, "oauth_provider_id": { "type": [ "string", "null" ], "description": "Stable provider id used for user-scoped OAuth connections." }, "protocol_mode": { "$ref": "#/components/schemas/McpProtocolMode", "description": "Protocol-era adoption policy for the MCP client (`auto` negotiates)." }, "status": { "$ref": "#/components/schemas/McpServerStatus", "description": "Current lifecycle status of the MCP server." }, "transport_type": { "$ref": "#/components/schemas/McpServerTransportType", "description": "Transport type (currently only HTTP supported)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the MCP server was last updated." }, "url": { "type": "string", "description": "URL of the MCP server endpoint.", "example": "https://mcp.atlassian.com/v1/mcp" } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." } } }, "ListResponse_WithUrls_Model": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "LLM Model entity", "required": [ "id", "provider_id", "model_id", "display_name", "capabilities", "is_favorite", "enabled", "source", "created_at", "updated_at" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability tags supported by this model (e.g. `chat`, `tools`, `vision`)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was created (RFC 3339)." }, "display_name": { "type": "string", "description": "Human-readable display name. Safe to render in user-facing messages." }, "enabled": { "type": "boolean", "description": "Whether this model is selectable. Controls UI visibility AND server-side resolution: `ProviderResolverService` requires `enabled = true`, and org default-model validation rejects disabled models. Disabled models stay visible in raw list endpoints (so admins can re-enable them) but cannot be used in active sessions or as a session/agent default." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "model_01933b5a00007000800000000000001" }, "is_favorite": { "type": "boolean", "description": "Whether this model is starred in the UI for quick access." }, "model_id": { "type": "string", "description": "Provider-side model identifier as sent on the wire (e.g. `gpt-5.2`, `claude-sonnet-5`)." }, "provider_id": { "type": "string", "description": "Owning provider's prefixed public identifier.", "example": "provider_01933b5a00007000800000000000001" }, "source": { "$ref": "#/components/schemas/ModelSource", "description": "How this model entry was added (manually, discovered, or seeded as predefined)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was last updated (RFC 3339)." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." } } }, "ListResponse_WithUrls_ModelWithProvider": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "LLM Model with provider info", "required": [ "id", "provider_id", "model_id", "display_name", "capabilities", "is_favorite", "enabled", "source", "created_at", "updated_at", "provider_name", "provider_type", "healthy" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability tags supported by this model.", "example": [ "text", "tools", "vision", "thinking" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was created (RFC 3339).", "example": "2026-01-04T11:23:00Z" }, "display_name": { "type": "string", "description": "Human-readable display name.", "example": "Claude Sonnet 4.5" }, "enabled": { "type": "boolean", "description": "Whether this model is selectable. Controls UI visibility AND server-side resolution: `ProviderResolverService` requires `enabled = true`, and org default-model validation rejects disabled models.", "example": true }, "healthy": { "type": "boolean", "description": "Derived: model is configured and ready for use. Currently means the\njoined provider is active and has an API key set; over time this may\nalso incorporate live reachability checks. Not persisted.", "example": true }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "model_01933b5a00007000800000000000001" }, "is_favorite": { "type": "boolean", "description": "Whether this model is starred in the UI for quick access.", "example": true }, "model_id": { "type": "string", "description": "Provider-side model identifier as sent on the wire (e.g. `gpt-5.2`).", "example": "claude-sonnet-4-5" }, "model_vendor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelVendor", "description": "Vendor/brand of the model, derived from the model registry. Drives UI\nbranding (icons). `None` when the model id is not in the registry. Not persisted." } ] }, "profile": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelProfile", "description": "Readonly profile with model capabilities (limits, pricing, modalities). Not persisted." } ] }, "provider_id": { "type": "string", "description": "Owning provider's prefixed public identifier.", "example": "provider_01933b5a00007000800000000000001" }, "provider_name": { "type": "string", "description": "Joined provider display name.", "example": "Anthropic" }, "provider_type": { "$ref": "#/components/schemas/DriverId", "description": "Joined provider implementation type." }, "source": { "$ref": "#/components/schemas/ModelSource", "description": "How this model entry was added (manually, discovered, or seeded as predefined)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was last updated (RFC 3339).", "example": "2026-05-27T15:24:00Z" } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." } } }, "ListResponse_WithUrls_Provider": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "LLM Provider entity (API keys never exposed)\nNote: This is the entity struct, separate from the Provider trait in llm.rs", "required": [ "id", "name", "provider_type", "api_key_set", "status", "managed", "created_at", "updated_at" ], "properties": { "api_key_set": { "type": "boolean", "description": "Whether an API key is configured. The key itself is never returned." }, "base_url": { "type": [ "string", "null" ], "description": "Custom base URL for self-hosted / proxied providers. `None` means use the provider's default endpoint." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this provider was created (RFC 3339)." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "provider_01933b5a00007000800000000000001" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent successful model sync from the provider's API (RFC 3339)." }, "managed": { "type": "boolean", "description": "Whether this provider is host-managed (EVE-810). A managed provider is\nprovisioned by the host/embedder; the OSS API rejects tenant PATCH/DELETE\non it (403). Read-only to org admins. Defaults to `false`." }, "name": { "type": "string", "description": "Human-readable provider name. Safe to render in user-facing messages." }, "provider_type": { "$ref": "#/components/schemas/DriverId", "description": "Provider implementation type (OpenAI, Anthropic, Gemini, etc.)." }, "request_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderRequestOptions", "description": "Extra headers and diagnostics options applied to every request sent to\nthis provider. `None` when the org configured nothing." } ] }, "status": { "$ref": "#/components/schemas/ProviderStatus", "description": "Current lifecycle status of this provider." }, "trace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderTraceConfig", "description": "Resolved trace/observability link configuration: the driver's default\ntemplates overlaid with this provider's stored overrides. `None` when the\ndriver exposes no dashboard and the org configured nothing." } ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this provider was last updated (RFC 3339)." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." } } }, "ListResponse_WithUrls_ResourceWithCounts_Harness": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "allOf": [ { "type": "object", "description": "Harness configuration for sessions.\nA harness defines the base behavior and capabilities that apply to all sessions.", "required": [ "id", "name", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was archived.", "example": "2026-05-26T00:00:00Z" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities enabled for this harness with per-harness configuration." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was created.", "example": "2026-04-01T10:00:00Z" }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model ID for this harness.\nLowest priority in chain: controls > session > agent > harness.", "example": "model_01933b5a00007000800000000000001" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was deleted.", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the harness does.", "example": "Default harness with file-system + secrets capabilities; safe baseline for new agents." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI.", "example": "Generic Harness" }, "embedder_metadata": { "type": "object", "description": "Arbitrary key-value metadata injected into LLM requests for observability.\nKeys from system context (session_id, org_id, etc.) always take precedence.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": { "env": "production", "team": "platform" } }, "icon": { "type": [ "string", "null" ], "description": "Display glyph name rendered by the UI (e.g. \"message-circle\").\n\nBuilt-in harnesses declare it in their definition; custom harnesses\nleave it unset and fall back to the UI's generic harness glyph.", "example": "message-circle" }, "id": { "type": "string", "description": "Unique identifier for the harness (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this harness." }, "intro_markdown": { "type": [ "string", "null" ], "description": "Optional Markdown intro rendered as an intro box at the top of a fresh\nPlatform Chat thread. Images are allowed. The agent intro wins over\nthe harness intro. Hidden once the user inputs.", "example": "I can triage incidents, dig through logs, and draft the update." }, "is_built_in": { "type": "boolean", "description": "Whether this harness is built-in (system-managed, readonly).\nBuilt-in harnesses are provisioned during org initialization and\ncannot be modified or deleted via the API. Users can copy them.", "example": false }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this harness and inherited by descendant layers." }, "name": { "type": "string", "description": "Name, unique per org (e.g. \"generic\").", "example": "generic" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs sessions can reach.\nMerged with agent and session layers (allowed: intersect, blocked: union)." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "parent_harness_id": { "type": [ "string", "null" ], "description": "Optional parent harness that this harness inherits from.", "example": "harness_01933b5a000070008000000000000602" }, "short_description": { "type": [ "string", "null" ], "description": "Optional one-line description in simplified Markdown, shown below the\nchat title once the intro is hidden. The agent value wins.", "example": "Knows your agents, harnesses, models, and runs." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. The agent's\nstarters win when non-empty, otherwise the harness's apply." }, "status": { "$ref": "#/components/schemas/HarnessStatus", "description": "Current lifecycle status of the harness." }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt that defines the harness's base behavior.\n\nForms the foundation of the prompt stack. Optional: when absent the\nharness contributes no base prompt, so the effective prompt comes\nentirely from the parent harness (if any), the agent, the session, and\ncapability contributions. Empty/whitespace-only values normalize to\n`None`.", "example": "You are an Everruns agent. Be concise, cite sources when possible, and decline tasks outside your assigned scope." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering harnesses.", "example": [ "baseline", "production" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was last updated.", "example": "2026-05-20T14:00:00Z" } } }, { "type": "object", "required": [ "session_count", "app_count" ], "properties": { "app_count": { "type": "integer", "format": "int64", "description": "Number of non-deleted apps using this resource.", "minimum": 0 }, "session_count": { "type": "integer", "format": "int64", "description": "Number of sessions using this resource.", "minimum": 0 } } } ], "description": "Wrapper that flattens lightweight relationship counts into resource responses." }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." } } }, "ListResponse_WithUrls_Skill": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Skill entity (API response type)", "required": [ "id", "name", "description", "source_type", "status", "version", "created_at", "updated_at" ], "properties": { "allowed_tools": { "type": [ "string", "null" ], "description": "Comma-separated list of tool patterns this skill may invoke. `None` means inherit from the harness." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this skill was archived, if any (RFC 3339). Archived skills are hidden from default list views." }, "compatibility": { "type": [ "string", "null" ], "description": "Compatibility marker describing host-runtime requirements declared by the skill (e.g. min platform version). Informational." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this skill was created (RFC 3339)." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this skill was hard-deleted, if any (RFC 3339)." }, "description": { "type": "string", "description": "Short, agent- and user-readable summary of what the skill does and when to use it.", "example": "Extract text and tables from PDF files." }, "disable_model_invocation": { "type": "boolean", "description": "When `true`, the LLM is prevented from auto-invoking this skill; only the user can trigger it explicitly." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "skill_01933b5a00007000800000000000001" }, "license": { "type": [ "string", "null" ], "description": "License string as declared by the skill author (e.g. `MIT`, `Apache-2.0`). Informational; not enforced." }, "metadata": { "type": "object", "description": "Free-form metadata declared by the skill author.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Stable kebab-case slug used to invoke the skill (e.g. `/pdf-processing` in chat). Safe to render in user-facing messages.", "example": "pdf-processing" }, "source_type": { "$ref": "#/components/schemas/SkillSourceType", "description": "How the skill content is sourced (filesystem, URL, embedded). Determines reload semantics." }, "status": { "$ref": "#/components/schemas/SkillStatus", "description": "Current lifecycle status (`active`, `archived`, `deleted`)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this skill was last updated (RFC 3339)." }, "user_invocable": { "type": "boolean", "description": "Whether this skill appears as a `/`-prefixed slash command for end users in chat UIs." }, "version": { "type": "string", "description": "Semver string declared by the skill author. Free-form; sorted lexicographically when comparing." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." } } }, "ListResponse_Workspace": { "type": "object", "description": "Response wrapper for list endpoints.\nAll list endpoints return responses wrapped in a `data` field.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ], "example": "Shared workspace for the Q4 research project" }, "id": { "type": "string", "example": "wsp_01933b5a000070008000000000000001" }, "name": { "type": "string", "example": "team-research" }, "status": { "type": "string", "example": "active" }, "updated_at": { "type": "string", "format": "date-time" } } }, "description": "Array of items returned by the list operation." } } }, "ListSchedulesQuery": { "type": "object", "description": "Query parameters for `GET /v1/schedules` — optional enabled/target-type\nfilters plus standard offset/limit paging.", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Filter by enabled status", "example": true }, "limit": { "type": [ "integer", "null" ], "format": "int32", "description": "Pagination limit (default: 20, max: 100)", "example": 20, "minimum": 0 }, "offset": { "type": [ "integer", "null" ], "format": "int32", "description": "Pagination offset", "example": 0, "minimum": 0 }, "target_type": { "type": [ "string", "null" ], "description": "Filter by target type (\"workflow\" or \"activity\")", "example": "workflow" } } }, "ListUsersQuery": { "type": "object", "description": "Query parameters for listing users", "properties": { "search": { "type": [ "string", "null" ], "description": "Search query to filter by name or email" } } }, "ListWorkspacesQuery": { "type": "object", "properties": { "include_archived": { "type": "boolean" }, "search": { "type": [ "string", "null" ] } } }, "LlmCompactionInfo": { "type": "object", "description": "Information about context compaction performed before LLM generation\n\nWhen the conversation context exceeds the model's limit, compaction is\nautomatically triggered to compress the context before retrying.", "required": [ "compacted" ], "properties": { "compacted": { "type": "boolean", "description": "Whether compaction was performed" }, "cost_usd": { "type": [ "number", "null" ], "format": "double", "description": "Provider-reported cost of the compaction call itself, in USD.\n\nCompaction is a separate billable model call, so its cost is also folded\ninto the generation's `usage.actual_cost_usd` — that is what budgets and\n`llm_generations` read. This field keeps the split visible, so an\noperator can see how much of a turn's spend was compaction (EVE-895)." }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Duration of the compaction operation in milliseconds", "minimum": 0 }, "input_tokens_after": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of input tokens after compaction", "minimum": 0 }, "input_tokens_before": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of input tokens before compaction", "minimum": 0 } } }, "LlmGenerationData": { "type": "object", "description": "Data for llm.generation event\n\nEmitted after each LLM API call to provide full visibility into\nthe messages sent to the model and the response received.", "required": [ "messages", "output", "metadata" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeMessage" }, "description": "Messages sent to the LLM (including system prompt)" }, "metadata": { "$ref": "#/components/schemas/LlmGenerationMetadata", "description": "Metadata about the generation" }, "output": { "$ref": "#/components/schemas/LlmGenerationOutput", "description": "Output from the LLM" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinitionSummary" }, "description": "Tools available to the LLM for this generation" } } }, "LlmGenerationMetadata": { "type": "object", "description": "Metadata about an LLM generation", "required": [ "model", "success" ], "properties": { "compaction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LlmCompactionInfo", "description": "Compaction information if context was compressed before generation\nOccurs when the conversation context exceeded the model's limit" } ] }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Duration of the generation in milliseconds", "example": 1842, "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Error message if generation failed", "example": "provider returned 503" }, "finish_reasons": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Finish reasons from the LLM (e.g., [\"stop\"], [\"tool_calls\"])\nRequired for gen-ai semantic conventions", "example": [ "tool_calls" ] }, "model": { "type": "string", "description": "Model identifier used for generation", "example": "claude-sonnet-4-5" }, "provider": { "type": [ "string", "null" ], "description": "Provider type (openai, anthropic, etc.)", "example": "anthropic" }, "request_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LlmRequestOptions", "description": "Request-side driver options that were enabled for this generation." } ] }, "response_id": { "type": [ "string", "null" ], "description": "Unique response identifier from the LLM provider\nRequired for gen-ai semantic conventions", "example": "msg_01ABCDef0123456789" }, "response_model": { "type": [ "string", "null" ], "description": "Model the provider reported actually serving the request.\n\n`model` is what was *asked for*, which is routinely an alias that\nresolves at request time — `claude-sonnet-4-5` served by\n`claude-sonnet-4-5-20250929`, or an OpenRouter route landing on one\nupstream of several. Collapsing the two loses the only record of which\nweights produced the answer, which is what a regression in output\nquality has to be correlated against.\n\n`None` when the provider reported no model, which is the honest answer:\nconsumers fall back to `model` rather than being told the alias was\nconfirmed.", "example": "claude-sonnet-4-5-20250929" }, "retry": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LlmRetryInfo", "description": "Retry information if rate limit retries occurred\nContains number of retries and total wait time" } ] }, "success": { "type": "boolean", "description": "Whether the generation was successful", "example": true }, "time_to_first_token_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Time to first token in milliseconds (streaming latency)", "example": 312, "minimum": 0 }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Token usage statistics" } ] } } }, "LlmGenerationOutput": { "type": "object", "description": "LLM generation output", "properties": { "text": { "type": [ "string", "null" ], "description": "Text response from the model" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Tool calls requested by the model" } } }, "LlmPromptCacheInfo": { "type": "object", "description": "Request-side prompt cache settings for an LLM generation.", "required": [ "enabled", "strategy" ], "properties": { "enabled": { "type": "boolean", "description": "Whether prompt caching was enabled on the request." }, "provider_mode": { "type": [ "string", "null" ], "description": "Provider-specific prompt-cache mode used by the driver." }, "strategy": { "$ref": "#/components/schemas/PromptCacheStrategy", "description": "Strategy used to enable prompt caching." } } }, "LlmRequestOptions": { "type": "object", "description": "Request options applied to an LLM generation.\n\nThese fields capture request-side intent such as prompt caching or deferred\ntool loading. They complement `usage`, which captures what actually happened.", "properties": { "max_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum output tokens requested, when set.", "minimum": 0 }, "metadata": { "type": "object", "description": "General request metadata passed to the LLM provider for tracking and observability.\nIncludes embedder-supplied labels merged with system tracking keys (session_id, turn_id, etc.).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "prompt_cache": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LlmPromptCacheInfo", "description": "Prompt caching configuration for this request." } ] }, "provider_options": { "type": "object", "description": "Provider-specific request options that do not warrant dedicated fields.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "reasoning_effort": { "type": [ "string", "null" ], "description": "Reasoning / thinking effort level requested, as the string sent to the\nprovider (`low`, `medium`, `high`, ...), when set." }, "stream": { "type": [ "boolean", "null" ], "description": "Whether the request used the provider's streaming mode." }, "temperature": { "type": [ "number", "null" ], "format": "float", "description": "Sampling temperature sent with the request, when set." }, "tool_search": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LlmToolSearchInfo", "description": "Deferred tool-loading configuration for this request." } ] } } }, "LlmRetryInfo": { "type": "object", "description": "Information about rate limit retries during LLM generation", "required": [ "attempts", "total_wait_ms" ], "properties": { "attempts": { "type": "integer", "format": "int32", "description": "Number of retry attempts made (0 = succeeded on first try)", "minimum": 0 }, "total_wait_ms": { "type": "integer", "format": "int64", "description": "Total time spent waiting between retries in milliseconds", "minimum": 0 } } }, "LlmToolSearchInfo": { "type": "object", "description": "Request-side tool_search settings for an LLM generation.", "required": [ "enabled", "threshold" ], "properties": { "enabled": { "type": "boolean", "description": "Whether tool_search was enabled on the request." }, "threshold": { "type": "integer", "description": "Minimum number of tools before deferred loading activates.", "minimum": 0 } } }, "LogQuery": { "type": "object", "description": "Query for log endpoint", "properties": { "limit": { "type": [ "integer", "null" ], "description": "Max commits to return (default: 50)", "example": 50, "minimum": 0 }, "ref": { "type": [ "string", "null" ], "description": "Ref to start from (default: HEAD)", "example": "HEAD" } } }, "ManageSessionSandboxRequest": { "type": "object", "description": "Request body for the `manage_session_sandbox` operation.", "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/SessionSandboxAction", "description": "Action to take on the sandbox (`reset`, `delete`, etc.)." } } }, "ManageSessionSandboxResponse": { "type": "object", "description": "Response body for the `manage_session_sandbox` operation.", "required": [ "action", "exists", "deleted" ], "properties": { "action": { "$ref": "#/components/schemas/SessionSandboxAction", "description": "Action that was taken." }, "deleted": { "type": "boolean", "description": "Whether the action deleted the sandbox (`true` after a successful `delete`)." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable sandbox label." }, "exists": { "type": "boolean", "description": "Whether a sandbox instance still exists after the action." }, "external_id": { "type": [ "string", "null" ], "description": "Provider-side sandbox identifier." }, "provider": { "type": [ "string", "null" ], "description": "Sandbox provider (`daytona`, `e2b`, `docker`, etc.)." }, "session_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SessionSandboxStatusValue", "description": "Current sandbox lifecycle status after the action." } ] }, "workspace_path": { "type": [ "string", "null" ], "description": "Absolute path of the sandbox workspace root." } } }, "ManualMemorySourceResponse": { "type": "object", "description": "Response body for manual memory source." }, "McpErrorCategory": { "type": "string", "description": "Broad-strokes routing hint sitting alongside the precise [`McpErrorCode`].\nThe categories are stable enough that an LLM can pick a recovery\nstrategy from this field alone (e.g. retry transients with backoff,\nsurface validation errors to the user, escalate auth failures).", "enum": [ "transient", "permanent", "validation", "auth", "unknown" ] }, "McpErrorCode": { "type": "string", "description": "Closed vocabulary of error codes for Everruns' own MCP `tools/call`\nexecute path. Surfaces in [`McpExecuteError::code`] so LLM toolcallers\ncan branch on a machine-readable value instead of regexing prose.\n\nNew variants are a spec change. SDKs should treat any value they don't\nrecognise as `unknown` (forward-compat) — serde's `#[serde(other)]`\ncatch-all enables that on the deserialize side.", "enum": [ "tool_not_found", "tool_timeout", "tool_panicked", "invalid_arguments", "permission_denied", "quota_exceeded", "network_blocked", "mcp_server_unreachable", "internal", "unknown" ] }, "McpExecuteError": { "type": "object", "description": "Typed structured-error envelope returned by Everruns' MCP `tools/call`\nexecute path. Serialized into the MCP `structuredContent` field on\nerror responses so the legacy `content[0].text` channel stays\nbackward-compatible; new SDKs prefer the typed envelope.\n\nSee `knowledge/integrations/mcp.md` for the error contract.", "required": [ "code", "message", "category", "retryable" ], "properties": { "category": { "$ref": "#/components/schemas/McpErrorCategory", "description": "Broad-strokes recovery category." }, "cause_chain": { "type": "array", "items": { "type": "string" }, "description": "Chain of upstream error messages, oldest cause first. Useful for\ndebugging; SDKs should not treat this as machine-readable." }, "code": { "$ref": "#/components/schemas/McpErrorCode", "description": "Machine-readable error code. Closed vocabulary; SDKs that see an\nunrecognised value should map it to `unknown`." }, "hint": { "type": [ "string", "null" ], "description": "Short, agent-readable recovery hint. Free-form; one or two sentences." }, "message": { "type": "string", "description": "Human-readable error message. Mirrors the legacy\n`content[0].text` string for backward compat." }, "retry_after_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Seconds the caller should wait before retrying. Set on\n`tool_timeout`, `quota_exceeded`, and upstream-unreachable cases\nwhen the server has a concrete back-off hint.", "minimum": 0 }, "retryable": { "type": "boolean", "description": "`true` when the same call is worth retrying. Distinct from\n`category == \"transient\"` because a server may know about a\nnon-transient retry path (e.g. a transient `Internal`)." } } }, "McpProtocolMode": { "type": "string", "description": "Per-server policy for which MCP protocol era the client uses.\n\n`Auto` (the default) probes the server and adapts — it tries the stateless\n`2026-07-28` path first and transparently falls back to the stateful\nhandshake when a server demands it, so a single configuration speaks to\nevery era without operator action. The pinned variants skip negotiation when\nan operator knows a server's era (or to work around a server that\nmis-signals it).\n\nWire values are the version dates. The pre-release names (`legacy`,\n`stable`, `rc`) stay accepted as deserialization aliases so stored config\nkeeps loading, but they are no longer emitted.", "enum": [ "auto", "2025-03-26", "2025-06-18", "2026-07-28" ], "example": "auto" }, "McpServer": { "type": "object", "description": "MCP Server configuration.\nRepresents a remote MCP server that can provide tools and resources.", "required": [ "id", "name", "url", "transport_type", "status", "api_key_set", "created_at", "updated_at" ], "properties": { "api_key_set": { "type": "boolean", "description": "Whether an API key has been configured." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the MCP server was archived." }, "auth_mode": { "$ref": "#/components/schemas/McpServerAuthMode", "description": "Authentication mode for this MCP server." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the MCP server was created." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the MCP server was deleted." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the MCP server.", "example": "Atlassian MCP Server for Jira and Confluence" }, "headers": { "type": "object", "description": "Additional HTTP headers for authentication.\nKeys are header names, values are header values.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Unique identifier for the MCP server.", "example": "mcp_01933b5a00007000800000000000001" }, "name": { "type": "string", "description": "Display name of the MCP server.", "example": "atlassian-mcp-server" }, "oauth_provider_id": { "type": [ "string", "null" ], "description": "Stable provider id used for user-scoped OAuth connections." }, "protocol_mode": { "$ref": "#/components/schemas/McpProtocolMode", "description": "Protocol-era adoption policy for the MCP client (`auto` negotiates)." }, "status": { "$ref": "#/components/schemas/McpServerStatus", "description": "Current lifecycle status of the MCP server." }, "transport_type": { "$ref": "#/components/schemas/McpServerTransportType", "description": "Transport type (currently only HTTP supported)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the MCP server was last updated." }, "url": { "type": "string", "description": "URL of the MCP server endpoint.", "example": "https://mcp.atlassian.com/v1/mcp" } } }, "McpServerActsAs": { "type": "string", "description": "Identity whose OAuth grant a scoped MCP attachment requests.", "enum": [ "none", "service", "user" ], "example": "service" }, "McpServerAuthMode": { "type": "string", "description": "MCP server authentication mode.", "enum": [ "none", "api_key", "oauth" ], "example": "api_key" }, "McpServerCatalogEntry": { "allOf": [ { "$ref": "#/components/schemas/WithUrls_McpServer", "description": "MCP server preset and its resource URLs." }, { "type": "object", "required": [ "used_by_agents" ], "properties": { "used_by_agents": { "type": "integer", "format": "int64", "description": "Number of active agents that use this preset.", "example": 2 } } } ], "description": "MCP server preset with its active-agent usage count." }, "McpServerCatalogResponse": { "type": "object", "description": "One page of MCP server catalog entries for the selected organization.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerCatalogEntry" }, "description": "MCP server presets in this page.", "example": [ { "id": "mcp_01933b5a00007000800000000000001", "name": "microsoft_learn", "url": "https://learn.microsoft.com/api/mcp", "used_by_agents": 2 } ] }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the final page.", "example": "mcp_01933b5a00007000800000000000001" } } }, "McpServerPresetRef": { "type": "string", "description": "Reference to an organization MCP server catalog entry.", "example": "catalog:linear" }, "McpServerStatus": { "type": "string", "description": "MCP Server lifecycle status.\n- `active`: Server is available for use\n- `disabled`: Server is disabled and not used\n- `archived`: Server is hidden from listings and cannot be modified or assigned\n- `deleted`: Server is a tombstone kept only for historical references", "enum": [ "active", "disabled", "archived", "deleted" ], "example": "active" }, "McpServerTransportType": { "type": "string", "description": "MCP Server transport type.", "enum": [ "http", "stdio" ], "example": "http" }, "McpServerUsageResponse": { "type": "object", "description": "Bounded archive-impact summary for an MCP server preset.", "required": [ "agent_names", "total_count", "truncated" ], "properties": { "agent_names": { "type": "array", "items": { "type": "string" }, "description": "Names of active agents that use the preset, up to the response limit.", "example": [ "Docs agent", "Research agent" ] }, "total_count": { "type": "integer", "format": "int64", "description": "Total number of active agents that use the preset.", "example": 2 }, "truncated": { "type": "boolean", "description": "Whether additional agent names were omitted from the bounded list.", "example": false } } }, "McpToolAnnotations": { "type": "object", "description": "MCP tool annotations as defined by the MCP specification.\nAll fields are optional booleans following the MCP convention.", "properties": { "destructiveHint": { "type": [ "boolean", "null" ] }, "idempotentHint": { "type": [ "boolean", "null" ] }, "openWorldHint": { "type": [ "boolean", "null" ] }, "readOnlyHint": { "type": [ "boolean", "null" ] } } }, "Memory": { "type": "object", "description": "Response body for memory.", "required": [ "id", "name", "scope", "source_type", "source", "is_readonly", "sync_status", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was archived, if any (RFC 3339).", "example": "2026-05-26T00:00:00Z" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339).", "example": "2026-04-01T10:00:00Z" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was soft-deleted, if any (RFC 3339).", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Living design documents synced from GitHub" }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "mem_01933b5a000070008000000000000001" }, "is_readonly": { "type": "boolean", "description": "Whether the memory is mounted read-only into sessions. Read-only memories accept no writes from the session sandbox.", "example": false }, "last_sync_error": { "type": [ "string", "null" ], "description": "Most recent sync error message; cleared on the next successful sync.", "example": "ssh: connect to host github.com port 22: Connection timed out" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent successful sync (RFC 3339). `None` if never synced.", "example": "2026-05-25T08:00:00Z" }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "design-docs" }, "owner_agent_id": { "type": [ "string", "null" ], "description": "Owning agent when `scope = agent`.", "example": "agent_01933b5a000070008000000000000001" }, "owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Owning user when `scope = user`." }, "scope": { "type": "string", "description": "Ownership scope (`org`, `agent`, or `user`).", "example": "org" }, "source": { "$ref": "#/components/schemas/MemorySourceResponse", "description": "Source-specific configuration (git remote, github repo, manual upload)." }, "source_type": { "type": "string", "description": "Source kind discriminator (`manual`, `git`, `github`). Determines which `source` variant is populated.", "example": "github" }, "status": { "type": "string", "description": "Current lifecycle status.", "example": "active" }, "sync_status": { "type": "string", "description": "Current sync status (`idle`, `syncing`, `succeeded`, `failed`). Only meaningful when `source_type` is `git` or `github`.", "example": "succeeded" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339).", "example": "2026-05-25T08:00:00Z" } } }, "MemoryFile": { "type": "object", "required": [ "path", "content", "encoding", "size_bytes", "created_at", "updated_at" ], "properties": { "content": { "type": "string", "description": "Text or base64-encoded content; check `encoding`." }, "content_hash": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "encoding": { "type": "string", "description": "\"text\" or \"base64\"." }, "path": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MemoryFileInfo": { "type": "object", "required": [ "path", "is_directory", "size_bytes", "created_at", "updated_at" ], "properties": { "content_hash": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "is_directory": { "type": "boolean" }, "path": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MemoryGrepResult": { "type": "object", "required": [ "path", "size_bytes" ], "properties": { "path": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" } } }, "MemorySourceResponse": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ManualMemorySourceResponse" }, { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "manual" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/GitHubMemorySourceResponse" }, { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "github" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/GitMemorySourceResponse" }, { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "git" ] } } } ] } ], "description": "Response body for memory source." }, "Message": { "type": "object", "description": "Message - primary conversation data (API response)", "required": [ "id", "session_id", "sequence", "role", "content", "created_at" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" }, "description": "Array of content parts.\n\nReasoning artifacts appear here as `reasoning` parts, in the order the\nprovider emitted them, with opaque replay state (signatures, encrypted\npayloads) stripped." }, "controls": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Controls", "description": "Runtime controls (model, reasoning, etc.)" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "external_actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalActor", "description": "External actor identity (for messages from external channels like Slack)" } ] }, "id": { "type": "string", "description": "Unique message ID (format: message_{32-hex})", "example": "message_01933b5a00007000800000000000001" }, "metadata": { "type": [ "object", "null" ], "description": "Message-level metadata (locale, etc.)", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExecutionPhase", "description": "Execution phase for agent messages: whether this is intermediate\n`commentary` or the turn's `final_answer`. Absent on user messages.\n\nWithout this a client cannot tell an intermediate message from the\nanswer, which is the single question most consumers of a session need\nanswered." } ] }, "phase_source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PhaseSource", "description": "Whether `phase` was reported by the provider or inferred by the runtime\nfrom tool-call presence.\n\n`derived` is a weak signal: it means only \"this message called tools\",\nso a text-only preamble is reported as `final_answer`. Clients needing a\ndependable classification should treat `derived` accordingly." } ] }, "role": { "$ref": "#/components/schemas/MessageRole" }, "sequence": { "type": "integer", "format": "int32" }, "session_id": { "type": "string", "description": "Session ID this message belongs to (format: session_{32-hex})", "example": "session_01933b5a00007000800000000000001" } } }, "MessageBody": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Message text dispatched to the agent.", "example": "Summarize the latest support tickets." } } }, "MessageRole": { "type": "string", "description": "Message role (API layer)\n\nSimplified to only user and agent messages.\nTool results are conveyed via `tool.completed` events.\nSystem messages are internal and not exposed via API.", "enum": [ "user", "agent" ] }, "MetricsPoint": { "type": "object", "description": "Single metrics data point", "required": [ "timestamp", "running_workflows", "pending_workflows", "pending_tasks", "claimed_tasks", "active_workers", "load_percentage", "dlq_size", "tasks_completed_total", "tasks_failed_total", "tasks_started_total", "workflows_completed_total", "workflows_failed_total", "workflows_started_total" ], "properties": { "active_workers": { "type": "integer", "description": "Number of workers actively heartbeating (gauge).", "example": 4, "minimum": 0 }, "claimed_tasks": { "type": "integer", "description": "Number of tasks currently claimed by a worker (gauge).", "example": 28, "minimum": 0 }, "dlq_size": { "type": "integer", "description": "Size of the dead-letter queue (gauge).", "example": 3, "minimum": 0 }, "load_percentage": { "type": "number", "format": "double", "description": "Aggregate worker load as a percentage of total `max_concurrency` (0.0-100.0).", "example": 62.5 }, "pending_tasks": { "type": "integer", "description": "Number of tasks waiting to be claimed by a worker (gauge).", "example": 12, "minimum": 0 }, "pending_workflows": { "type": "integer", "description": "Number of workflows waiting to be claimed by a worker (gauge).", "example": 7, "minimum": 0 }, "running_workflows": { "type": "integer", "description": "Number of workflows currently executing (gauge).", "example": 42, "minimum": 0 }, "tasks_completed_total": { "type": "integer", "format": "int64", "description": "Cumulative count of tasks completed successfully since process start (monotonic counter).", "example": 12843, "minimum": 0 }, "tasks_failed_total": { "type": "integer", "format": "int64", "description": "Cumulative count of tasks that failed or were sent to the DLQ (monotonic counter).", "example": 17, "minimum": 0 }, "tasks_started_total": { "type": "integer", "format": "int64", "description": "Cumulative count of tasks claimed at least once (monotonic counter).", "example": 12873, "minimum": 0 }, "timestamp": { "type": "string", "format": "date-time", "description": "Sampling timestamp for this data point (RFC 3339).", "example": "2026-05-27T15:30:00Z" }, "workflows_completed_total": { "type": "integer", "format": "int64", "description": "Cumulative count of workflows that completed successfully (monotonic counter).", "example": 982, "minimum": 0 }, "workflows_failed_total": { "type": "integer", "format": "int64", "description": "Cumulative count of workflows that ended in failure (monotonic counter).", "example": 3, "minimum": 0 }, "workflows_started_total": { "type": "integer", "format": "int64", "description": "Cumulative count of workflows that started (monotonic counter).", "example": 1024, "minimum": 0 } } }, "MetricsTimeSeriesResponse": { "type": "object", "description": "Metrics time series response.\n\nIn multi-instance deployments, each instance maintains its own metrics\nring buffer. The `instance_count` field indicates how many instances\nare expected so consumers can aggregate or label appropriately.", "required": [ "points", "resolution_seconds" ], "properties": { "instance_count": { "type": "integer", "format": "int32", "description": "Number of expected control-plane instances (from EXPECTED_INSTANCES env).\nWhen >1, these metrics represent only this instance's view.", "minimum": 0 }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/MetricsPoint" } }, "resolution_seconds": { "type": "integer", "format": "int64", "minimum": 0 } } }, "Modality": { "type": "string", "description": "Modality type (text, image, audio, video)", "enum": [ "text", "image", "audio", "video", "pdf" ] }, "Model": { "type": "object", "description": "LLM Model entity", "required": [ "id", "provider_id", "model_id", "display_name", "capabilities", "is_favorite", "enabled", "source", "created_at", "updated_at" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability tags supported by this model (e.g. `chat`, `tools`, `vision`)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was created (RFC 3339)." }, "display_name": { "type": "string", "description": "Human-readable display name. Safe to render in user-facing messages." }, "enabled": { "type": "boolean", "description": "Whether this model is selectable. Controls UI visibility AND server-side resolution: `ProviderResolverService` requires `enabled = true`, and org default-model validation rejects disabled models. Disabled models stay visible in raw list endpoints (so admins can re-enable them) but cannot be used in active sessions or as a session/agent default." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "model_01933b5a00007000800000000000001" }, "is_favorite": { "type": "boolean", "description": "Whether this model is starred in the UI for quick access." }, "model_id": { "type": "string", "description": "Provider-side model identifier as sent on the wire (e.g. `gpt-5.2`, `claude-sonnet-5`)." }, "provider_id": { "type": "string", "description": "Owning provider's prefixed public identifier.", "example": "provider_01933b5a00007000800000000000001" }, "source": { "$ref": "#/components/schemas/ModelSource", "description": "How this model entry was added (manually, discovered, or seeded as predefined)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was last updated (RFC 3339)." } } }, "ModelCost": { "type": "object", "description": "Cost information for the model (per million tokens)", "required": [ "input", "output" ], "properties": { "cache_read": { "type": [ "number", "null" ], "format": "double", "description": "Cached read cost per million tokens (USD), if supported" }, "cache_write": { "type": [ "number", "null" ], "format": "double", "description": "Cache write cost per million tokens (USD); absent falls back to input." }, "cost_tiers": { "type": "array", "items": { "$ref": "#/components/schemas/CostTier" }, "description": "Tiered pricing that applies when prompt tokens exceed context thresholds.\nWhen present, the highest matching tier replaces the base rates for the\nwhole request." }, "input": { "type": "number", "format": "double", "description": "Input cost per million tokens (USD)" }, "output": { "type": "number", "format": "double", "description": "Output cost per million tokens (USD)" } } }, "ModelLimits": { "type": "object", "description": "Token limits for the model", "required": [ "context", "output" ], "properties": { "context": { "type": "integer", "format": "int32", "description": "Maximum context window size in tokens" }, "input": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum input tokens (if different from context - output)" }, "max_media": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum images or PDF pages per request" }, "output": { "type": "integer", "format": "int32", "description": "Maximum output tokens" } } }, "ModelMetadata": { "type": "object", "description": "Metadata about the model used for generation", "required": [ "model" ], "properties": { "model": { "type": "string", "description": "Model name (e.g., \"gpt-5.6-sol\", \"claude-sonnet-5\")" }, "model_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Model ID (internal identifier)" }, "provider_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Provider ID (internal identifier)" } } }, "ModelModalities": { "type": "object", "description": "Model modalities for input and output", "required": [ "input", "output" ], "properties": { "input": { "type": "array", "items": { "$ref": "#/components/schemas/Modality" }, "description": "Supported input modalities" }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/Modality" }, "description": "Supported output modalities" } } }, "ModelProfile": { "type": "object", "description": "LLM Model Profile describing model capabilities\nBased on models.dev structure ()\n\nThe registry of profiles lives in `crate::profiles`; retired models are\ndropped from it as vendors sunset them.", "required": [ "name", "family", "attachment", "reasoning", "temperature", "tool_call", "structured_output", "open_weights" ], "properties": { "attachment": { "type": "boolean", "description": "Whether the model supports file/image attachments" }, "cost": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelCost", "description": "Cost per million tokens" } ] }, "description": { "type": [ "string", "null" ], "description": "Short human-readable description of the model's strengths and intended use" }, "family": { "type": "string", "description": "Model family (e.g., \"gpt-5.6-sol\", \"claude-sonnet-5\")" }, "knowledge": { "type": [ "string", "null" ], "description": "Knowledge cutoff date (YYYY-MM-DD format)" }, "last_updated": { "type": [ "string", "null" ], "description": "Last updated date (YYYY-MM-DD format)" }, "limits": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelLimits", "description": "Token limits" } ] }, "modalities": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelModalities", "description": "Supported modalities" } ] }, "name": { "type": "string", "description": "Display name of the model" }, "open_weights": { "type": "boolean", "description": "Whether the model has open weights" }, "reasoning": { "type": "boolean", "description": "Whether the model has reasoning/chain-of-thought capabilities" }, "reasoning_effort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningEffortConfig", "description": "Reasoning effort configuration (for reasoning models)" } ] }, "release_date": { "type": [ "string", "null" ], "description": "Release date (YYYY-MM-DD format)" }, "speed": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpeedConfig", "description": "Speed (service tier) configuration, for models served with\nselectable latency/price tiers (OpenAI `service_tier`)." } ] }, "structured_output": { "type": "boolean", "description": "Whether the model supports structured output (JSON mode)" }, "supported_parameters": { "type": "array", "items": { "type": "string" }, "description": "Provider-advertised request parameters supported by this model." }, "supports_phases": { "type": "boolean", "description": "Whether the model supports native execution phases (\"commentary\" / \"final_answer\").\nWhen true, the driver sends the `phase` field on assistant messages in the wire format.\nCurrently supported by GPT-5.4 and newer via OpenAI Responses API." }, "temperature": { "type": "boolean", "description": "Whether temperature control is supported" }, "tool_call": { "type": "boolean", "description": "Whether the model supports tool/function calling" }, "tool_search": { "type": "boolean", "description": "Whether the model supports tool_search (deferred tool loading).\nWhen true, the driver can use namespaces and defer_loading to reduce\ntoken usage for large tool sets. Currently supported by GPT-5.4 and newer." }, "verbosity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VerbosityConfig", "description": "Verbosity configuration, for models that expose output-length\ncontrol (OpenAI `verbosity`)." } ] } } }, "ModelSource": { "type": "string", "description": "How the model was added to the system", "enum": [ "manual", "discovered", "predefined" ], "example": "predefined" }, "ModelVendor": { "type": "string", "description": "Vendor / brand that authored a model. Independent of the provider type\nthat serves it (the same model may be offered by several providers or\ngateways). Primarily drives UI iconography.", "enum": [ "openai", "anthropic", "google", "nvidia", "qwen", "microsoft", "meta", "minimax", "moonshot", "xai", "llmsim" ] }, "ModelWithProvider": { "type": "object", "description": "LLM Model with provider info", "required": [ "id", "provider_id", "model_id", "display_name", "capabilities", "is_favorite", "enabled", "source", "created_at", "updated_at", "provider_name", "provider_type", "healthy" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability tags supported by this model.", "example": [ "text", "tools", "vision", "thinking" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was created (RFC 3339).", "example": "2026-01-04T11:23:00Z" }, "display_name": { "type": "string", "description": "Human-readable display name.", "example": "Claude Sonnet 4.5" }, "enabled": { "type": "boolean", "description": "Whether this model is selectable. Controls UI visibility AND server-side resolution: `ProviderResolverService` requires `enabled = true`, and org default-model validation rejects disabled models.", "example": true }, "healthy": { "type": "boolean", "description": "Derived: model is configured and ready for use. Currently means the\njoined provider is active and has an API key set; over time this may\nalso incorporate live reachability checks. Not persisted.", "example": true }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "model_01933b5a00007000800000000000001" }, "is_favorite": { "type": "boolean", "description": "Whether this model is starred in the UI for quick access.", "example": true }, "model_id": { "type": "string", "description": "Provider-side model identifier as sent on the wire (e.g. `gpt-5.2`).", "example": "claude-sonnet-4-5" }, "model_vendor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelVendor", "description": "Vendor/brand of the model, derived from the model registry. Drives UI\nbranding (icons). `None` when the model id is not in the registry. Not persisted." } ] }, "profile": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelProfile", "description": "Readonly profile with model capabilities (limits, pricing, modalities). Not persisted." } ] }, "provider_id": { "type": "string", "description": "Owning provider's prefixed public identifier.", "example": "provider_01933b5a00007000800000000000001" }, "provider_name": { "type": "string", "description": "Joined provider display name.", "example": "Anthropic" }, "provider_type": { "$ref": "#/components/schemas/DriverId", "description": "Joined provider implementation type." }, "source": { "$ref": "#/components/schemas/ModelSource", "description": "How this model entry was added (manually, discovered, or seeded as predefined)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was last updated (RFC 3339).", "example": "2026-05-27T15:24:00Z" } } }, "MoveFileRequest": { "type": "object", "description": "Request to move/rename a file", "required": [ "src_path", "dst_path" ], "properties": { "dst_path": { "type": "string", "description": "Destination path (relative to the workspace filesystem root).", "example": "docs/migration-plan.md" }, "src_path": { "type": "string", "description": "Source path (relative to the workspace filesystem root).", "example": "drafts/migration-plan.md" } } }, "MyInvitationResponse": { "type": "object", "required": [ "id", "org_name", "role" ], "properties": { "id": { "type": "string" }, "org_name": { "type": "string" }, "role": { "type": "string" } } }, "NativeToolCall": { "oneOf": [ { "type": "object", "required": [ "call_id", "name", "arguments", "type" ], "properties": { "arguments": { "type": "string", "description": "Complete JSON arguments, preserved exactly as received.", "example": "{\"query\":\"weather in Paris\"}" }, "async": { "type": "boolean", "description": "Whether execution may start before response generation completes.", "example": true }, "call_id": { "type": "string", "description": "Original provider call identity used when delivering the result.", "example": "call_lookup_1" }, "name": { "type": "string", "description": "Registered function or custom tool name.", "example": "lookup" }, "type": { "type": "string", "enum": [ "function_call" ] } } }, { "type": "object", "required": [ "call_id", "name", "input", "type" ], "properties": { "async": { "type": "boolean", "description": "Whether execution may start before response generation completes.", "example": true }, "call_id": { "type": "string", "description": "Original provider call identity used when delivering the result.", "example": "call_lookup_1" }, "input": { "type": "string", "description": "Raw custom-tool input, without JSON normalization.", "example": "weather in Paris" }, "name": { "type": "string", "description": "Registered function or custom tool name.", "example": "lookup" }, "type": { "type": "string", "enum": [ "custom_tool_call" ] } } } ], "description": "A complete provider-native call, retaining its original identity and payload.", "example": { "arguments": "{\"query\":\"weather in Paris\"}", "async": true, "call_id": "call_lookup_1", "name": "lookup", "type": "function_call" } }, "NetworkAccessList": { "type": "object", "description": "Network access list controlling which hosts/URLs an agent session can reach.\n\n- `allowed`: if non-empty, only URLs matching these patterns are permitted.\n- `blocked`: URLs matching these patterns are always denied (takes precedence over allowed).\n\nPattern format:\n- `example.com` — exact domain match (any port, any path)\n- `*.example.com` — domain and all subdomains\n- `https://example.com/api/` — exact URL prefix (scheme + host + path)", "properties": { "allowed": { "type": "array", "items": { "type": "string" }, "description": "Allowed host patterns. If non-empty, only matching URLs are permitted.\nAn empty list means \"no restriction from this layer\" (inherit parent)." }, "blocked": { "type": "array", "items": { "type": "string" }, "description": "Blocked host patterns. Always denied, even if matched by `allowed`." } }, "example": { "allowed": [ "*.example.com", "https://api.acme.com/" ], "blocked": [ "169.254.169.254" ] } }, "OkfFileInput": { "type": "object", "description": "A single inline bundle file, for callers that send files as JSON rather\nthan a tarball.", "required": [ "path", "content" ], "properties": { "content": { "type": "string", "description": "Raw markdown file content (frontmatter + body)." }, "path": { "type": "string", "description": "Bundle-relative path, e.g. `tables/orders.md`." } } }, "OkfImportSummary": { "type": "object", "description": "Outcome of an import run.", "required": [ "created", "updated", "skipped", "pruned", "warnings" ], "properties": { "created": { "type": "integer", "minimum": 0 }, "pruned": { "type": "integer", "description": "Entries removed because `prune` was set and they were absent from the bundle.", "minimum": 0 }, "skipped": { "type": "integer", "description": "Documents skipped (e.g. oversized body); see `warnings`.", "minimum": 0 }, "updated": { "type": "integer", "minimum": 0 }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues (broken docs, oversized bodies). OKF consumers degrade gracefully." } } }, "OrgFeatureFlagSetting": { "type": "object", "required": [ "name", "label", "description", "experimental", "platform_managed", "system_enabled", "org_enabled", "effective" ], "properties": { "description": { "type": "string" }, "effective": { "type": "boolean", "description": "Effective value (`system_enabled && org_enabled`)." }, "experimental": { "type": "boolean" }, "label": { "type": "string" }, "name": { "type": "string" }, "org_enabled": { "type": "boolean", "description": "Whether the organization has opted in." }, "platform_managed": { "type": "boolean", "description": "Whether only a platform user may enable this flag for the org." }, "system_enabled": { "type": "boolean", "description": "Whether the deployment allows this flag (env / grade)." } } }, "OrgFeatureFlagsSettingsResponse": { "type": "object", "required": [ "flags" ], "properties": { "flags": { "type": "array", "items": { "$ref": "#/components/schemas/OrgFeatureFlagSetting" } } } }, "OrganizationResponse": { "type": "object", "description": "Response for organization operations", "required": [ "id", "name", "default_provider_per_service", "created_at", "updated_at" ], "properties": { "base_harness_id": { "type": [ "string", "null" ], "description": "Base harness used when session creation omits harness_id." }, "created_at": { "type": "string", "format": "date-time", "description": "When the organization was created" }, "default_harness_id": { "type": [ "string", "null" ], "description": "Default harness to preselect in the UI." }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model for the organization." }, "default_provider_per_service": { "type": "object", "description": "Org-level default provider per service (EVE-569), keyed by service kind.\nEmpty when no org defaults are configured.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "External identifier (org_<32-hex-chars>)" }, "name": { "type": "string", "description": "Display name" }, "onboarding_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the org's creator finished or skipped the setup wizard. `null` means\nonboarding is still incomplete, which the UI uses to resume the user at\n`/orgs/{id}/setup`. Seeded/default and externally-synced orgs are complete." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the organization was last updated" } } }, "OutputMessageCompletedData": { "type": "object", "description": "Data for output.message.completed event", "required": [ "message" ], "properties": { "error_code": { "type": [ "string", "null" ], "description": "Stable error code for user-facing failures surfaced as assistant text." }, "error_disclosure": { "type": [ "string", "null" ], "description": "Error-disclosure mode applied to `error_code`/`error_fields`\n(\"generic\" | \"standard\" | \"detailed\"). Tracking metadata; absent for\nnon-error messages and for paths that predate disclosure modes." }, "error_fields": { "type": [ "object", "null" ], "description": "Structured interpolation fields for localized error rendering." }, "message": { "$ref": "#/components/schemas/RuntimeMessage", "description": "The agent message" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelMetadata", "description": "Metadata about the model used" } ] }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Token usage" } ] } } }, "OutputMessageDeltaData": { "type": "object", "description": "Data for output.message.delta event\n\nIncremental text update during LLM generation. Events are batched (~100ms)\nto reduce volume while providing real-time feedback.", "required": [ "turn_id", "message_id", "delta", "accumulated" ], "properties": { "accumulated": { "type": "string", "description": "Accumulated text so far" }, "delta": { "type": "string", "description": "The new text chunk" }, "message_id": { "type": "string", "description": "Stable public ID for this assistant message across its streaming lifecycle.\nThis is the same identifier as `OutputMessageCompletedData.message.id`.", "example": "message_550e8400e29b41d4a716446655440000" }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExecutionPhase", "description": "Best-effort streamed phase hint (EVE-774).\n\n`None` means \"not yet classified — treat as ordinary assistant text\",\nNEVER \"thinking\". Refinement is monotonic: once a stream reveals a native\nphase (`Commentary` or `FinalAnswer`) it stays fixed for the rest of the\nmessage — it never flip-flops and never reverts to `None`\n(see `ExecutionPhase::refine_streamed_hint`). Providers without native\nmid-stream phase (Anthropic, Gemini, …) leave this `None` until\ncompletion. The authoritative classification remains the completed\n`RuntimeMessage.phase`. See `knowledge/execution/events.md`." } ] }, "turn_id": { "type": "string", "description": "Turn ID this delta belongs to", "example": "turn_01933b5a00007000800000000000001" } } }, "OutputMessageReplacedData": { "type": "object", "description": "Data for `output.message.replaced` event.\n\nEmitted between the last (suppressed) `output.message.delta` and the final\n`output.message.completed`. Tells the client to discard the text accumulated\nfor `message_id` and use `replacement` as that assistant message's text. The\noriginal model output is never persisted or replayed.", "required": [ "turn_id", "message_id", "guardrail_capability_id", "guardrail_id", "reason_code", "replacement" ], "properties": { "guardrail_capability_id": { "type": "string", "description": "Stable ID of the capability that contributed the guardrail\n(e.g. `\"prompt_canary_guardrail\"`)." }, "guardrail_id": { "type": "string", "description": "Stable ID of the guardrail itself (e.g. `\"prompt_canary\"`)." }, "message_id": { "type": "string", "description": "Stable public ID for the assistant message whose streamed text is replaced.\nThis is the same identifier as the subsequent completed `RuntimeMessage.id`.", "example": "message_550e8400e29b41d4a716446655440000" }, "reason_code": { "type": "string", "description": "Stable machine-readable reason code (e.g. `\"system_prompt_leak\"`).\nClients localize their copy from this rather than the human text." }, "replacement": { "type": "string", "description": "Replacement text shown to the user and stored as the assistant message." }, "turn_id": { "type": "string", "description": "Turn ID this replacement belongs to.", "example": "turn_01933b5a00007000800000000000001" } } }, "OutputMessageStartedData": { "type": "object", "description": "Data for output.message.started event\n\nEmitted when the LLM starts generating a response. UI can show a\n\"thinking\" indicator until output.message.delta or output.message.completed events arrive.", "required": [ "turn_id", "message_id" ], "properties": { "iteration": { "type": [ "integer", "null" ], "format": "int32", "description": "Current iteration number within this turn (1-based).\nUseful for UI to show progress during multi-step tool-calling flows.", "minimum": 0 }, "message_id": { "type": "string", "description": "Stable public ID for this assistant message across its streaming lifecycle.\nThis is the same identifier as `OutputMessageCompletedData.message.id`.", "example": "message_550e8400e29b41d4a716446655440000" }, "model": { "type": [ "string", "null" ], "description": "Optional model name being used" }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExecutionPhase", "description": "Best-effort streamed phase hint (EVE-774).\n\n`None` means \"not yet classified — treat as ordinary assistant text\",\nNEVER \"thinking\". A missing/unknown phase must fall back to the\nassistant-text channel, never the reasoning channel. Only populated when\nthe provider stream reveals a native phase before this event is emitted;\ntoday `output.message.started` is emitted before the LLM call, so this is\ngenerally `None` at start. The authoritative classification remains the\ncompleted `RuntimeMessage.phase`. See `knowledge/execution/events.md`." } ] }, "reasoning_state": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningState", "description": "Prepared Astra effort state, persisted before the provider call so an\ninterrupted worker can resume without changing the request baseline." } ] }, "turn_id": { "type": "string", "description": "Turn ID this output belongs to", "example": "turn_01933b5a00007000800000000000001" } } }, "PaginatedResponse_Session": { "type": "object", "description": "Response wrapper for paginated list endpoints.\nIncludes pagination metadata along with the data array.\n\n`next_url` and `prev_url` are populated by the [`decorate_pagination_links`]\nmiddleware after the handler returns, so handlers don't need to thread the\nrequest URL into every construction site.", "required": [ "data", "total", "offset", "limit" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Session - instance of agentic loop execution.\nA session represents a single conversation with an agent.", "required": [ "id", "organization_id", "workspace_id", "harness_id", "owner_principal_id", "status", "created_at", "updated_at" ], "properties": { "active_schedule_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of active (enabled) schedules for this session.\nPopulated when the session is fetched for API responses.", "example": 2, "minimum": 0 }, "activity": { "$ref": "#/components/schemas/SessionActivity", "description": "Outcome-oriented status derived from `status` and the last turn result.\nThis is the value the sessions list groups by and the facet rail counts." }, "agent_id": { "type": [ "string", "null" ], "description": "ID of the agent working in this session (format: agent_{32-hex}). Optional.", "example": "agent_01933b5a00007000800000000000001" }, "agent_identity_id": { "type": [ "string", "null" ], "description": "Optional resident agent identity for unattended/background execution.", "example": "identity_01933b5a00007000800000000000001" }, "agent_version_id": { "type": [ "string", "null" ], "description": "Immutable agent version captured when the session was created or rebound.", "example": "agentver_01933b5a00007000800000000000001" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When this session was archived; `None` means active. Archived sessions\nare hidden from default list results and shown by opting in\n(`include_archived=true`). Unlike `is_pinned`, archive is a property of\nthe session itself rather than of the viewer.", "example": "2026-05-25T10:14:32Z" }, "blueprint_config": { "type": [ "object", "null" ], "description": "Validated config passed by host at blueprint spawn time.\nExample: `{\"target_repo\": \"acme/everruns\"}`." }, "blueprint_id": { "type": [ "string", "null" ], "description": "Blueprint ID. When set, reason_activity and act_activity build RuntimeAgent\nfrom the blueprint definition instead of from harness_id/agent_id.", "example": "blueprint_research_pack" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Session-level capabilities (additive to agent capabilities).\nApplied after agent capabilities when building RuntimeAgent." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was created.", "example": "2026-05-25T10:00:00Z" }, "effective_owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Effective human owner summary." } ] }, "event_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Total events recorded for this session (EVE-868). Read from the\ndenormalized `sessions.event_count` counter rather than counted, so the\nsession detail tab bar costs no extra scan over `events`.\n`None` on payloads built outside the database read path.", "example": 42, "minimum": 0 }, "features": { "type": "array", "items": { "type": "string" }, "description": "Aggregated UI features from all active capabilities (harness + agent + session).\nComputed at read time from the capability registry.\nKnown features: \"file_system\", \"schedules\", \"secrets\", \"key_value\",\n\"sql_database\", \"leased_resources\".", "example": [ "file_system", "secrets" ] }, "file_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Non-directory files in this session's workspace (EVE-868). Read from\n`workspaces.file_count`. Counts persisted files only: capability-provided\nvirtual mounts are served from memory and are not included.", "example": 6, "minimum": 0 }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the session finished (completed or failed).", "example": "2026-05-25T10:14:32Z" }, "forked_from_sequence": { "type": [ "integer", "null" ], "format": "int32", "description": "Parent event sequence the fork was taken at (the fork point). NULL unless\nthis session is a fork.", "example": 42 }, "forked_from_session_id": { "type": [ "string", "null" ], "description": "Session this one was forked from. NULL for sessions that were not forked.\nDistinct from `parent_session_id` (subagent nesting): forking is a\nuser-initiated \"branch from here\" relationship." }, "goal": { "type": [ "string", "null" ], "description": "Session objective visible to the runtime agent at system-prompt level.", "example": "Investigate the queue latency regression" }, "harness_id": { "type": "string", "description": "ID of the harness for this session (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "hints": { "type": [ "object", "null" ], "description": "Session-level client hints — arbitrary key-value pairs declared by the\nclient at session creation time. These are defaults for every turn;\nper-message `controls.hints` override these key-by-key (shallow merge).\n\nExamples: `{\"setup_connection\": true, \"rich_media\": true}`", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Unique identifier for the session (format: session_{32-hex}).", "example": "session_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Session-level initial files (additive to agent initial_files).\nFiles with matching paths override agent/harness files; new paths are appended." }, "is_pinned": { "type": [ "boolean", "null" ], "description": "Whether this session is pinned by the current user.\nOnly populated when the request has an authenticated user context.", "example": false }, "locale": { "type": [ "string", "null" ], "description": "Locale for localized agent behavior and formatting (BCP 47, e.g. `uk-UA`).", "example": "en-US" }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this session.", "example": 50, "minimum": 0 }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this session only." }, "model_id": { "type": [ "string", "null" ], "description": "LLM model ID to use for this session (format: model_{32-hex}).\nOverrides the agent's default model if set.", "example": "model_01933b5a00007000800000000000001" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs this session can reach.\nMerged with harness and agent layers (allowed: intersect, blocked: union)." } ] }, "organization_id": { "type": "string", "description": "Organization this session belongs to (format: org_{32-hex}).", "example": "org_00000000000000000000000000000001" }, "output_preview": { "type": [ "string", "null" ], "description": "Preview text from the last assistant response (truncated).", "example": "Here is a Q3 plan covering the three pillars we discussed..." }, "owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Owning principal summary." } ] }, "owner_principal_id": { "type": "string", "description": "Owning principal for this session.", "example": "principal_01933b5a000070008000000000000001" }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "parent_session_id": { "type": [ "string", "null" ], "description": "Parent session that spawned this subagent. NULL for top-level sessions.\nUsed to compute governed subagent delegation depth." }, "preview": { "type": [ "string", "null" ], "description": "Preview text from the first user message (truncated).", "example": "Help me draft the Q3 marketing plan" }, "resolved_owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Denormalized effective human owner of the owning principal lineage.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "run_summary": { "type": [ "string", "null" ], "description": "Generated one-sentence description of what the run did, and where it\nfailed (EVE-867). Absent until a terminal turn has been summarised, and\nalways absent for chat threads and for deployments with no utility LLM,\nso a reader must have a fallback rather than treating this as required.", "example": "Ran the nightly report and failed posting it to Slack: channel_not_found." }, "source": { "$ref": "#/components/schemas/SessionSource", "description": "How this session was started. Server-owned for every ingress path." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the session started executing.", "example": "2026-05-25T10:00:01Z" }, "status": { "$ref": "#/components/schemas/SessionStatus", "description": "Current execution status of the session." }, "system_prompt": { "type": [ "string", "null" ], "description": "Session-level system prompt override.\nPrepended to the agent's system prompt when building RuntimeAgent." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering sessions.", "example": [ "marketing", "q3", "draft" ] }, "task_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Background work owned by this session — subagents, external agents and\nbackground tools (EVE-868). Read from `sessions.task_count`. This is\nwhat the Work tab holds; `active_schedule_count` describes only the\nschedules it also lists.", "example": 3, "minimum": 0 }, "title": { "type": [ "string", "null" ], "description": "Human-readable title for the session.", "example": "Q3 marketing brief" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools for this session (additive to agent tools)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was last updated.", "example": "2026-05-25T10:14:32Z" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative token usage for all LLM calls in this session." } ] }, "workspace_id": { "type": "string", "description": "Workspace this session is attached to (format: wsp_{32-hex}). Owns the\nsession's virtual filesystem. For the default 1:1 case this mirrors the\nsession id, but clients should read it here rather than deriving it.", "example": "wsp_01933b5a00007000800000000000001" } } }, "description": "Array of items returned by the list operation." }, "limit": { "type": "integer", "format": "int32", "description": "Maximum number of items per page.", "minimum": 0 }, "next_url": { "type": [ "string", "null" ], "description": "Absolute URL for the next page, with `offset` advanced by `limit`. Omitted from the response (field absent) when this is the last page." }, "offset": { "type": "integer", "format": "int32", "description": "Current offset (starting position).", "minimum": 0 }, "prev_url": { "type": [ "string", "null" ], "description": "Absolute URL for the previous page, with `offset` rolled back by `limit`. Omitted from the response (field absent) when this is the first page." }, "total": { "type": "integer", "format": "int32", "description": "Total number of items matching the query (across all pages).", "minimum": 0 } } }, "PaginatedResponse_WithUrls_AgentWithCounts": { "type": "object", "description": "Response wrapper for paginated list endpoints.\nIncludes pagination metadata along with the data array.\n\n`next_url` and `prev_url` are populated by the [`decorate_pagination_links`]\nmiddleware after the handler returns, so handlers don't need to thread the\nrequest URL into every construction site.", "required": [ "data", "total", "offset", "limit" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/Agent" }, { "type": "object", "required": [ "session_count", "app_count", "effective_harness" ], "properties": { "app_count": { "type": "integer", "format": "int64", "minimum": 0 }, "effective_harness": { "$ref": "#/components/schemas/AgentHarnessSummary" }, "session_count": { "type": "integer", "format": "int64", "minimum": 0 } } } ], "description": "Agent list/detail payload with relationship counts and resolved harness metadata." }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." }, "limit": { "type": "integer", "format": "int32", "description": "Maximum number of items per page.", "minimum": 0 }, "next_url": { "type": [ "string", "null" ], "description": "Absolute URL for the next page, with `offset` advanced by `limit`. Omitted from the response (field absent) when this is the last page." }, "offset": { "type": "integer", "format": "int32", "description": "Current offset (starting position).", "minimum": 0 }, "prev_url": { "type": [ "string", "null" ], "description": "Absolute URL for the previous page, with `offset` rolled back by `limit`. Omitted from the response (field absent) when this is the first page." }, "total": { "type": "integer", "format": "int32", "description": "Total number of items matching the query (across all pages).", "minimum": 0 } }, "x-sdk-response-wrapper": { "kind": "list", "model": "#/components/schemas/Agent" } }, "PaginatedResponse_WithUrls_CapabilityInfo": { "type": "object", "description": "Response wrapper for paginated list endpoints.\nIncludes pagination metadata along with the data array.\n\n`next_url` and `prev_url` are populated by the [`decorate_pagination_links`]\nmiddleware after the handler returns, so handlers don't need to thread the\nrequest URL into every construction site.", "required": [ "data", "total", "offset", "limit" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Public capability information (without internal details)\nThis is what gets returned from the API\nNamed CapabilityInfo to distinguish from the Capability trait", "required": [ "id", "name", "description", "status" ], "properties": { "agent_count": { "type": "integer", "format": "int64", "description": "Number of active agents referencing this capability in the org.", "example": 42, "minimum": 0 }, "category": { "type": [ "string", "null" ], "description": "Category for grouping in UI", "example": "filesystem" }, "config_schema": { "type": "object", "description": "JSON Schema for capability-specific per-agent config." }, "config_ui_schema": { "type": "object", "description": "react-jsonschema-form uiSchema hints for rendering config_schema." }, "dependencies": { "type": "array", "items": { "type": "string" }, "description": "IDs of capabilities that this capability depends on.\nWhen this capability is selected, its dependencies are automatically included.", "example": [ "approval" ] }, "description": { "type": "string", "description": "Description of what this capability provides", "example": "Read, write, edit, list, grep, delete, and stat files in the session workspace." }, "docs_slug": { "type": [ "string", "null" ], "description": "Slug under https://dev.everruns.com/capabilities/ when public docs exist.", "example": "session_file_system" }, "features": { "type": "array", "items": { "type": "string" }, "description": "UI feature strings this capability contributes to.\nMultiple capabilities can contribute the same feature.", "example": [ "file_browser" ] }, "harness_count": { "type": "integer", "format": "int64", "description": "Number of active harnesses referencing this capability in the org.", "example": 7, "minimum": 0 }, "icon": { "type": [ "string", "null" ], "description": "Icon name (for UI rendering)", "example": "Folder" }, "id": { "type": "string", "description": "Unique capability identifier", "example": "session_file_system" }, "is_guardrail": { "type": "boolean", "description": "Whether this capability is a guardrail (constrains agent behavior\nrather than granting abilities). Used for UI grouping and filtering.", "example": false }, "is_mcp": { "type": "boolean", "description": "Whether this is an MCP server capability (for UI badge)", "example": false }, "is_skill": { "type": "boolean", "description": "Whether this is an Agent Skill capability (for UI badge)", "example": false }, "localizations": { "type": "object", "description": "Localized display strings keyed by lowercase language tag (e.g. \"uk\").\nThe \"en\" entry carries only `config_description`, since the base\nname/description/config_schema strings are already English.", "additionalProperties": { "$ref": "#/components/schemas/CapabilityLocalizationInfo" }, "propertyNames": { "type": "string" }, "example": { "uk": { "description": "Монтує спільні файли пам'яті в сесії.", "name": "Пам'ять" } } }, "name": { "type": "string", "description": "Display name", "example": "Session File System" }, "risk_level": { "$ref": "#/components/schemas/RiskLevel", "description": "TM-AGENT-005: Risk level. High-risk capabilities require admin approval." }, "status": { "type": "string", "description": "Current status", "example": "active" }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt addition contributed by this capability", "example": "You can read and write files in /workspace via the session_file_system tools." }, "tool_definitions": { "type": "array", "items": { "type": "object" }, "description": "Tool definitions provided by this capability", "example": [ { "description": "Read a file from the session workspace.", "name": "read_file" }, { "description": "Write or overwrite a file in the session workspace.", "name": "write_file" } ] } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." }, "limit": { "type": "integer", "format": "int32", "description": "Maximum number of items per page.", "minimum": 0 }, "next_url": { "type": [ "string", "null" ], "description": "Absolute URL for the next page, with `offset` advanced by `limit`. Omitted from the response (field absent) when this is the last page." }, "offset": { "type": "integer", "format": "int32", "description": "Current offset (starting position).", "minimum": 0 }, "prev_url": { "type": [ "string", "null" ], "description": "Absolute URL for the previous page, with `offset` rolled back by `limit`. Omitted from the response (field absent) when this is the first page." }, "total": { "type": "integer", "format": "int32", "description": "Total number of items matching the query (across all pages).", "minimum": 0 } }, "x-sdk-response-wrapper": { "kind": "list", "model": "#/components/schemas/CapabilityInfo" } }, "PaginatedResponse_WithUrls_Session": { "type": "object", "description": "Response wrapper for paginated list endpoints.\nIncludes pagination metadata along with the data array.\n\n`next_url` and `prev_url` are populated by the [`decorate_pagination_links`]\nmiddleware after the handler returns, so handlers don't need to thread the\nrequest URL into every construction site.", "required": [ "data", "total", "offset", "limit" ], "properties": { "data": { "type": "array", "items": { "allOf": [ { "type": "object", "description": "Session - instance of agentic loop execution.\nA session represents a single conversation with an agent.", "required": [ "id", "organization_id", "workspace_id", "harness_id", "owner_principal_id", "status", "created_at", "updated_at" ], "properties": { "active_schedule_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of active (enabled) schedules for this session.\nPopulated when the session is fetched for API responses.", "example": 2, "minimum": 0 }, "activity": { "$ref": "#/components/schemas/SessionActivity", "description": "Outcome-oriented status derived from `status` and the last turn result.\nThis is the value the sessions list groups by and the facet rail counts." }, "agent_id": { "type": [ "string", "null" ], "description": "ID of the agent working in this session (format: agent_{32-hex}). Optional.", "example": "agent_01933b5a00007000800000000000001" }, "agent_identity_id": { "type": [ "string", "null" ], "description": "Optional resident agent identity for unattended/background execution.", "example": "identity_01933b5a00007000800000000000001" }, "agent_version_id": { "type": [ "string", "null" ], "description": "Immutable agent version captured when the session was created or rebound.", "example": "agentver_01933b5a00007000800000000000001" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When this session was archived; `None` means active. Archived sessions\nare hidden from default list results and shown by opting in\n(`include_archived=true`). Unlike `is_pinned`, archive is a property of\nthe session itself rather than of the viewer.", "example": "2026-05-25T10:14:32Z" }, "blueprint_config": { "type": [ "object", "null" ], "description": "Validated config passed by host at blueprint spawn time.\nExample: `{\"target_repo\": \"acme/everruns\"}`." }, "blueprint_id": { "type": [ "string", "null" ], "description": "Blueprint ID. When set, reason_activity and act_activity build RuntimeAgent\nfrom the blueprint definition instead of from harness_id/agent_id.", "example": "blueprint_research_pack" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Session-level capabilities (additive to agent capabilities).\nApplied after agent capabilities when building RuntimeAgent." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was created.", "example": "2026-05-25T10:00:00Z" }, "effective_owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Effective human owner summary." } ] }, "event_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Total events recorded for this session (EVE-868). Read from the\ndenormalized `sessions.event_count` counter rather than counted, so the\nsession detail tab bar costs no extra scan over `events`.\n`None` on payloads built outside the database read path.", "example": 42, "minimum": 0 }, "features": { "type": "array", "items": { "type": "string" }, "description": "Aggregated UI features from all active capabilities (harness + agent + session).\nComputed at read time from the capability registry.\nKnown features: \"file_system\", \"schedules\", \"secrets\", \"key_value\",\n\"sql_database\", \"leased_resources\".", "example": [ "file_system", "secrets" ] }, "file_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Non-directory files in this session's workspace (EVE-868). Read from\n`workspaces.file_count`. Counts persisted files only: capability-provided\nvirtual mounts are served from memory and are not included.", "example": 6, "minimum": 0 }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the session finished (completed or failed).", "example": "2026-05-25T10:14:32Z" }, "forked_from_sequence": { "type": [ "integer", "null" ], "format": "int32", "description": "Parent event sequence the fork was taken at (the fork point). NULL unless\nthis session is a fork.", "example": 42 }, "forked_from_session_id": { "type": [ "string", "null" ], "description": "Session this one was forked from. NULL for sessions that were not forked.\nDistinct from `parent_session_id` (subagent nesting): forking is a\nuser-initiated \"branch from here\" relationship." }, "goal": { "type": [ "string", "null" ], "description": "Session objective visible to the runtime agent at system-prompt level.", "example": "Investigate the queue latency regression" }, "harness_id": { "type": "string", "description": "ID of the harness for this session (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "hints": { "type": [ "object", "null" ], "description": "Session-level client hints — arbitrary key-value pairs declared by the\nclient at session creation time. These are defaults for every turn;\nper-message `controls.hints` override these key-by-key (shallow merge).\n\nExamples: `{\"setup_connection\": true, \"rich_media\": true}`", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Unique identifier for the session (format: session_{32-hex}).", "example": "session_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Session-level initial files (additive to agent initial_files).\nFiles with matching paths override agent/harness files; new paths are appended." }, "is_pinned": { "type": [ "boolean", "null" ], "description": "Whether this session is pinned by the current user.\nOnly populated when the request has an authenticated user context.", "example": false }, "locale": { "type": [ "string", "null" ], "description": "Locale for localized agent behavior and formatting (BCP 47, e.g. `uk-UA`).", "example": "en-US" }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this session.", "example": 50, "minimum": 0 }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this session only." }, "model_id": { "type": [ "string", "null" ], "description": "LLM model ID to use for this session (format: model_{32-hex}).\nOverrides the agent's default model if set.", "example": "model_01933b5a00007000800000000000001" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs this session can reach.\nMerged with harness and agent layers (allowed: intersect, blocked: union)." } ] }, "organization_id": { "type": "string", "description": "Organization this session belongs to (format: org_{32-hex}).", "example": "org_00000000000000000000000000000001" }, "output_preview": { "type": [ "string", "null" ], "description": "Preview text from the last assistant response (truncated).", "example": "Here is a Q3 plan covering the three pillars we discussed..." }, "owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Owning principal summary." } ] }, "owner_principal_id": { "type": "string", "description": "Owning principal for this session.", "example": "principal_01933b5a000070008000000000000001" }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "parent_session_id": { "type": [ "string", "null" ], "description": "Parent session that spawned this subagent. NULL for top-level sessions.\nUsed to compute governed subagent delegation depth." }, "preview": { "type": [ "string", "null" ], "description": "Preview text from the first user message (truncated).", "example": "Help me draft the Q3 marketing plan" }, "resolved_owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Denormalized effective human owner of the owning principal lineage.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "run_summary": { "type": [ "string", "null" ], "description": "Generated one-sentence description of what the run did, and where it\nfailed (EVE-867). Absent until a terminal turn has been summarised, and\nalways absent for chat threads and for deployments with no utility LLM,\nso a reader must have a fallback rather than treating this as required.", "example": "Ran the nightly report and failed posting it to Slack: channel_not_found." }, "source": { "$ref": "#/components/schemas/SessionSource", "description": "How this session was started. Server-owned for every ingress path." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the session started executing.", "example": "2026-05-25T10:00:01Z" }, "status": { "$ref": "#/components/schemas/SessionStatus", "description": "Current execution status of the session." }, "system_prompt": { "type": [ "string", "null" ], "description": "Session-level system prompt override.\nPrepended to the agent's system prompt when building RuntimeAgent." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering sessions.", "example": [ "marketing", "q3", "draft" ] }, "task_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Background work owned by this session — subagents, external agents and\nbackground tools (EVE-868). Read from `sessions.task_count`. This is\nwhat the Work tab holds; `active_schedule_count` describes only the\nschedules it also lists.", "example": 3, "minimum": 0 }, "title": { "type": [ "string", "null" ], "description": "Human-readable title for the session.", "example": "Q3 marketing brief" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools for this session (additive to agent tools)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was last updated.", "example": "2026-05-25T10:14:32Z" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative token usage for all LLM calls in this session." } ] }, "workspace_id": { "type": "string", "description": "Workspace this session is attached to (format: wsp_{32-hex}). Owns the\nsession's virtual filesystem. For the default 1:1 case this mirrors the\nsession id, but clients should read it here rather than deriving it.", "example": "wsp_01933b5a00007000800000000000001" } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "description": "Array of items returned by the list operation." }, "limit": { "type": "integer", "format": "int32", "description": "Maximum number of items per page.", "minimum": 0 }, "next_url": { "type": [ "string", "null" ], "description": "Absolute URL for the next page, with `offset` advanced by `limit`. Omitted from the response (field absent) when this is the last page." }, "offset": { "type": "integer", "format": "int32", "description": "Current offset (starting position).", "minimum": 0 }, "prev_url": { "type": [ "string", "null" ], "description": "Absolute URL for the previous page, with `offset` rolled back by `limit`. Omitted from the response (field absent) when this is the first page." }, "total": { "type": "integer", "format": "int32", "description": "Total number of items matching the query (across all pages).", "minimum": 0 } }, "x-sdk-response-wrapper": { "kind": "list", "model": "#/components/schemas/Session" } }, "PaymentAccount": { "type": "object", "description": "A payment account — the org-scoped source of funds for paid agent calls.\nEach account binds an owning principal (user, agent identity, or org)\nto one settlement rail and tracks its provisioning lifecycle.", "required": [ "id", "organization_id", "owner_type", "owner_id", "rail", "label", "status", "metadata", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this account was created (RFC 3339).", "example": "2026-04-01T10:00:00Z" }, "id": { "$ref": "#/components/schemas/payacctId", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." }, "label": { "type": "string", "description": "Human-readable label for this account. Safe to render in user-facing messages.", "example": "Production USDC ops wallet" }, "metadata": { "description": "Free-form metadata attached to this account (caller-defined; opaque to the platform)." }, "organization_id": { "type": "string", "description": "Owning organization's prefixed public identifier.", "example": "org_01933b5a000070008000000000000001" }, "owner_id": { "type": "string", "description": "Prefixed identifier of the owning principal (e.g. `user_…`, `agent_…`, `org_…`).", "example": "agent_01933b5a000070008000000000000001" }, "owner_type": { "$ref": "#/components/schemas/PaymentOwnerType", "description": "Principal class that owns this account (user, agent identity, or organization)." }, "public_address": { "type": [ "string", "null" ], "description": "Public address on the rail (chain address, account number, etc.). Optional; `None` until provisioning completes.", "example": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8" }, "rail": { "$ref": "#/components/schemas/PaymentRail", "description": "Settlement rail this account operates on." }, "status": { "$ref": "#/components/schemas/PaymentStatus", "description": "Current lifecycle status of this account." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this account was last updated (RFC 3339).", "example": "2026-05-20T14:00:00Z" } } }, "PaymentAttempt": { "type": "object", "description": "A single paid-call settlement attempt — the durable record of one\nauthorization+settlement cycle issued through the payment authority.\nPersisted regardless of outcome so failed attempts remain auditable.", "required": [ "id", "organization_id", "capability", "operation", "amount_usd", "currency", "target_url", "status", "receipt", "created_at", "updated_at" ], "properties": { "amount_usd": { "type": "number", "format": "double", "description": "Amount actually charged (USD).", "example": 0.014 }, "capability": { "type": "string", "description": "Capability ID that originated this paid call.", "example": "paid_search" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this attempt was created (RFC 3339).", "example": "2026-05-25T10:14:00Z" }, "currency": { "type": "string", "description": "ISO 4217 currency code for the charge (typically `USD`).", "example": "USD" }, "error_message": { "type": [ "string", "null" ], "description": "Human-readable error message when `status` is `failed`; `None` otherwise.", "example": "rail.insufficient_funds: settled balance below minimum" }, "id": { "$ref": "#/components/schemas/payattId", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." }, "operation": { "type": "string", "description": "Capability-specific operation name that originated this paid call.", "example": "search.query" }, "organization_id": { "type": "string", "description": "Owning organization's prefixed public identifier.", "example": "org_01933b5a000070008000000000000001" }, "payment_account_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/payacctId", "description": "Payment account that settled (or attempted to settle) this attempt. `None` if no account could be resolved." } ] }, "rail": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentRail", "description": "Settlement rail actually used. `None` if the attempt failed before rail selection." } ] }, "receipt": { "description": "Rail-specific receipt payload (transaction id, block reference, signature, etc.)." }, "request_hash": { "type": [ "string", "null" ], "description": "Stable hash of the outbound request used to detect replays. `None` when not applicable.", "example": "sha256:9f1e2a4c3d5b6e8a0b2c4d6e8f0a1b3c5d7e9f0a1b2c4d6e8f0a1b2c4d6e8f0a" }, "session_id": { "type": [ "string", "null" ], "description": "Session that initiated the paid call, if any.", "example": "session_01933b5a000070008000000000000001" }, "status": { "$ref": "#/components/schemas/PaymentStatus", "description": "Current lifecycle status of this attempt." }, "target_url": { "type": "string", "description": "Destination URL of the paid outbound call.", "example": "https://api.example.com/v1/search" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this attempt was last updated (RFC 3339).", "example": "2026-05-25T10:14:02Z" } } }, "PaymentOwnerType": { "type": "string", "description": "Principal class that owns a payment account.", "enum": [ "user", "agent_identity", "organization" ] }, "PaymentPolicy": { "type": "object", "description": "A payment policy — the binding between a paying account and a subject\n(agent identity, session) that controls which paid calls are\nauthorized and at what spend caps.", "required": [ "id", "organization_id", "payment_account_id", "subject_type", "subject_id", "allowed_capabilities", "allowed_hosts", "rail_preference", "status", "metadata", "created_at", "updated_at" ], "properties": { "allowed_capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability IDs this policy permits paid calls for. Empty list means no capability gating.", "example": [ "paid_search", "paid_image_gen" ] }, "allowed_hosts": { "type": "array", "items": { "type": "string" }, "description": "HTTP host allowlist for paid outbound calls. Empty list means no host gating.", "example": [ "api.openai.com", "api.anthropic.com" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this policy was created (RFC 3339).", "example": "2026-04-01T10:00:00Z" }, "id": { "$ref": "#/components/schemas/paypolId", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." }, "max_amount_usd_per_day": { "type": [ "number", "null" ], "format": "double", "description": "Maximum cumulative amount (USD) per UTC day. **Advisory only — not yet enforced.** Stored on the policy for forward compatibility; the payment authority currently checks only `max_amount_usd_per_request`. `None` means no per-day cap.", "example": 50.0 }, "max_amount_usd_per_request": { "type": [ "number", "null" ], "format": "double", "description": "Maximum amount (USD) any single paid request may settle for. **Enforced** by the payment authority at policy selection. `None` means no per-request cap.", "example": 2.5 }, "max_amount_usd_per_turn": { "type": [ "number", "null" ], "format": "double", "description": "Maximum cumulative amount (USD) per agent turn. **Advisory only — not yet enforced.** Stored on the policy for forward compatibility; the payment authority currently checks only `max_amount_usd_per_request`. `None` means no per-turn cap.", "example": 5.0 }, "metadata": { "description": "Free-form metadata attached to this policy." }, "organization_id": { "type": "string", "description": "Owning organization's prefixed public identifier.", "example": "org_01933b5a000070008000000000000001" }, "payment_account_id": { "$ref": "#/components/schemas/payacctId", "description": "Payment account this policy authorizes spending from." }, "rail_preference": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRail" }, "description": "Preferred settlement rails in priority order; the authority picks the first available." }, "require_approval_above_usd": { "type": [ "number", "null" ], "format": "double", "description": "Threshold (USD) above which a request would require explicit human approval. **Advisory only — not yet enforced.** Stored on the policy for forward compatibility; no approval gate is wired up yet. `None` disables the (future) gate.", "example": 10.0 }, "status": { "$ref": "#/components/schemas/PaymentStatus", "description": "Current lifecycle status of this policy." }, "subject_id": { "type": "string", "description": "Prefixed identifier of the bound subject.", "example": "identity_01933b5a000070008000000000000001" }, "subject_type": { "type": "string", "description": "Class of subject this policy binds to (e.g. `agent_identity`, `session`).", "example": "agent_identity" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this policy was last updated (RFC 3339).", "example": "2026-05-20T14:00:00Z" } } }, "PaymentRail": { "type": "string", "description": "Payment rail used to settle a machine payment.", "enum": [ "mpp_tempo", "x402_base" ] }, "PaymentStatus": { "type": "string", "description": "Lifecycle state of a payment account, policy, or attempt. The shared\nvocabulary keeps account/policy admin and attempt settlement on the\nsame status taxonomy.", "enum": [ "active", "disabled", "pending", "succeeded", "failed", "released" ] }, "PhaseSource": { "type": "string", "description": "Where a message's [`ExecutionPhase`] came from.\n\nOnly some providers report a phase. For the rest the runtime infers one from\ntool-call presence, where \"commentary\" means nothing more than \"this message\ncalled tools\" — so a text-only preamble is indistinguishable from a final\nanswer. Those are different claims, and a consumer cannot tell them apart\nfrom the phase value alone, so the source travels with it.", "enum": [ "provider", "derived" ] }, "PostTaskMessageBody": { "type": "object", "description": "Request body for posting an inbound task message.", "properties": { "content": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/TaskMessagePart" }, "description": "Structured message parts (alternative to `text`)." }, "in_reply_to": { "type": [ "string", "null" ], "description": "Input request ID this message answers, when applicable." }, "text": { "type": [ "string", "null" ], "description": "Plain-text message (alternative to `content`)." } } }, "PreviewAgentRequest": { "type": "object", "description": "Request to preview the final agent shape with capabilities applied", "required": [ "system_prompt" ], "properties": { "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities to apply with per-agent configuration.", "example": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "test_math" } ] }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to the previewed agent." }, "system_prompt": { "type": "string", "description": "The base system prompt (before capability additions)", "example": "You are a helpful customer support agent." }, "tools": { "type": "array", "items": { "type": "object" }, "description": "Client-side tools to include in the preview." } } }, "PreviewHarnessRequest": { "type": "object", "description": "Request to preview harness shape with capabilities applied", "properties": { "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capability configurations to layer onto the preview. Empty list means none.", "example": [ { "config": {}, "ref": "web.search" }, { "config": { "root": "/workspace" }, "ref": "filesystem.read" } ] }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "MCP servers scoped to this preview, keyed by scope (`shared` / per-agent / etc.).\nUse the camelCase key `mcpServers` (preferred) or the snake_case alias `mcp_servers`. Empty by default." }, "parent_harness_id": { "type": [ "string", "null" ], "description": "Parent harness to extend. When set, its prompt, capabilities, and MCP servers are\nmerged with the fields in this request before rendering.", "example": "harness_01933b5a000070008000000000000602" }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt to render as the base prompt for the preview. Optional:\nomit to preview a harness that contributes no base prompt of its own.", "example": "You are a research assistant." } } }, "PrincipalKind": { "type": "string", "description": "Class of principal that can hold permissions or own resources. `system`\nis reserved for platform-internal callers and is never minted via the\npublic API.", "enum": [ "user", "agent_identity", "system" ] }, "PrincipalSummary": { "type": "object", "description": "Compact view of a principal — id + kind + the subject-id pointer back\ninto the user/agent-identity row. Used wherever a full `Principal`\nwould be redundant (e.g. as a sub-field of a session or audit record).", "required": [ "id", "kind" ], "properties": { "id": { "type": "string", "example": "principal_01933b5a000070008000000000000001" }, "kind": { "$ref": "#/components/schemas/PrincipalKind" }, "metadata": {}, "subject_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "ProfileResponse": { "type": "object", "description": "Response from profile update", "required": [ "id", "email", "name" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." } } }, "ProjectorRunQuery": { "type": "object", "description": "Query parameters for a manual `POST /v1/reports/projector/run` invocation —\nthe cap on how many outbox rows one run is allowed to claim.", "properties": { "limit": { "type": "integer", "format": "int64", "description": "Maximum number of items returned in this page." } } }, "ProjectorRunResult": { "type": "object", "description": "Outcome of one projector run — how many outbox rows it claimed,\ncompleted, and failed. Returned by manual `POST /v1/reports/projector/run`\ncalls and useful for backfill scripting.", "required": [ "claimed", "completed", "failed" ], "properties": { "claimed": { "type": "integer", "description": "Number of outbox rows claimed by this run.", "minimum": 0 }, "completed": { "type": "integer", "description": "Number of claimed rows that completed successfully.", "minimum": 0 }, "failed": { "type": "integer", "description": "Number of claimed rows that failed and will be retried (or moved to `failed` after retry limit).", "minimum": 0 } } }, "PromptCacheStrategy": { "type": "string", "description": "Strategy for prompt caching.", "enum": [ "auto", "explicit" ] }, "Provider": { "type": "object", "description": "LLM Provider entity (API keys never exposed)\nNote: This is the entity struct, separate from the Provider trait in llm.rs", "required": [ "id", "name", "provider_type", "api_key_set", "status", "managed", "created_at", "updated_at" ], "properties": { "api_key_set": { "type": "boolean", "description": "Whether an API key is configured. The key itself is never returned." }, "base_url": { "type": [ "string", "null" ], "description": "Custom base URL for self-hosted / proxied providers. `None` means use the provider's default endpoint." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this provider was created (RFC 3339)." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "provider_01933b5a00007000800000000000001" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent successful model sync from the provider's API (RFC 3339)." }, "managed": { "type": "boolean", "description": "Whether this provider is host-managed (EVE-810). A managed provider is\nprovisioned by the host/embedder; the OSS API rejects tenant PATCH/DELETE\non it (403). Read-only to org admins. Defaults to `false`." }, "name": { "type": "string", "description": "Human-readable provider name. Safe to render in user-facing messages." }, "provider_type": { "$ref": "#/components/schemas/DriverId", "description": "Provider implementation type (OpenAI, Anthropic, Gemini, etc.)." }, "request_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderRequestOptions", "description": "Extra headers and diagnostics options applied to every request sent to\nthis provider. `None` when the org configured nothing." } ] }, "status": { "$ref": "#/components/schemas/ProviderStatus", "description": "Current lifecycle status of this provider." }, "trace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderTraceConfig", "description": "Resolved trace/observability link configuration: the driver's default\ntemplates overlaid with this provider's stored overrides. `None` when the\ndriver exposes no dashboard and the org configured nothing." } ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this provider was last updated (RFC 3339)." } } }, "ProviderRequestHeader": { "type": "object", "description": "One extra HTTP header sent with every request to a provider connection.", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Header name, e.g. `x-gateway-tenant`." }, "value": { "type": "string", "description": "Header value, sent verbatim." } } }, "ProviderRequestOptions": { "type": "object", "description": "Per-connection request options: what an org wants added to every outbound\nrequest to this provider, beyond endpoint and credentials.\n\nThese are connection-level on purpose. A gateway header or a diagnostics\nopt-in describes the *service* an org talks to, not one agent's behavior, so\nit belongs next to the base URL and credentials rather than on every agent.", "properties": { "cache_diagnostics": { "type": "boolean", "description": "Ask the provider to explain unexpected prompt-cache misses. Honored by\ndrivers with a diagnostics protocol (today: Anthropic's\n`cache-diagnosis` beta); ignored elsewhere." }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderRequestHeader" }, "description": "Extra HTTP headers added to every request to this provider. They\noverride the driver's and the connection's own headers by name, but\nconnection-level headers (`host`, `content-length`, ...) are ignored." } } }, "ProviderStatus": { "type": "string", "description": "LLM provider status", "enum": [ "active", "disabled" ] }, "ProviderTraceConfig": { "type": "object", "description": "Configuration for linking from the chat UI to a provider's observability\ndashboard (\"trace\"/\"logs\").\n\nThis is provider-agnostic: any driver with a dashboard can supply default\ntemplates (see [`DriverId::default_trace_templates`]), and an org enables\nlinks per provider once it has confirmed logging is on for that account.\nURL templates support the `{response_id}`, `{session_id}`, `{turn_id}` and\n`{model}` placeholders, so the same mechanism works for OpenRouter today and\nfor third-party observability backends (Langfuse, Helicone, ...) via an\noverride.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether trace links should be shown for this provider. Defaults to\n`false`: vendors typically do not retain trace content unless logging is\nexplicitly enabled, so the org opts in once that is set up." }, "generation_url_template": { "type": [ "string", "null" ], "description": "URL template for a single generation's trace, e.g.\n`\"https://openrouter.ai/logs?id={response_id}\"`." }, "session_url_template": { "type": [ "string", "null" ], "description": "URL template for a session's grouped trace, e.g.\n`\"https://openrouter.ai/logs\"`." } } }, "ProvidersConfigResponse": { "type": "object", "description": "Provider resource config: caller policies plus the credential schemas the UI\nrenders per driver.", "required": [ "policies", "drivers" ], "properties": { "drivers": { "type": "array", "items": { "$ref": "#/components/schemas/DriverCredentialInfo" }, "description": "Per-driver credential schemas, ordered by driver id." }, "policies": { "type": "object", "description": "Map of policy ID → whether the caller satisfies it.", "additionalProperties": { "type": "boolean" }, "propertyNames": { "type": "string" } } } }, "QuestionAnswersRequest": { "type": "object", "description": "Request to answer a pending `ask_user` question set.", "properties": { "answers": { "type": "array", "items": { "$ref": "#/components/schemas/SubmittedAnswer" }, "description": "One answer per asked question, keyed by question id.", "example": [ { "id": "target", "other_text": null, "selected": [ "Staging" ] } ] }, "status": { "$ref": "#/components/schemas/SubmittedStatus", "description": "What the person did. `answered` carries answers; `declined` is a finished\ndecision the model must not re-ask." }, "tool_call_id": { "type": [ "string", "null" ], "description": "The `ask_user` tool call being answered. Optional: when omitted the one\npending question set on the session is used.", "example": "toolu_01933b5a00007000800000000000001" } } }, "QuestionAnswersResponse": { "type": "object", "description": "Result of answering a pending question set.", "required": [ "status", "answered_by", "session_status" ], "properties": { "answered_by": { "type": "string", "description": "Who the server attributed the outcome to.", "example": "user" }, "session_status": { "type": "string", "description": "Session status after the answer.", "example": "active" }, "status": { "type": "string", "description": "Outcome recorded against the call.", "example": "answered" } } }, "ReasonCompletedData": { "type": "object", "description": "Data for reason.completed event", "required": [ "success", "has_tool_calls", "tool_call_count" ], "properties": { "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Duration of the reason phase in milliseconds", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Error message if failed" }, "has_tool_calls": { "type": "boolean", "description": "Whether tool calls were requested" }, "success": { "type": "boolean", "description": "Whether the LLM call succeeded" }, "text_preview": { "type": [ "string", "null" ], "description": "Text response preview (first 200 chars)" }, "tool_call_count": { "type": "integer", "format": "int32", "description": "Number of tool calls requested", "minimum": 0 }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Token usage from the LLM call" } ] } } }, "ReasonItemData": { "type": "object", "description": "Data for `reason.item` event.\n\nDurable record of one provider reasoning artifact.\n\nCarries identity and curated summary text only. Opaque replay state\n(signatures, encrypted reasoning context) is deliberately absent: it is\nstate the driver hands back to the provider, not content, and it must not\nreach an event stream or any API surface. Plaintext chain-of-thought is\nlikewise never persisted here.", "required": [ "turn_id", "provider", "item_id" ], "properties": { "item_id": { "type": "string", "description": "Provider-assigned identifier for the reasoning item." }, "model": { "type": [ "string", "null" ], "description": "Model identifier reported by the provider, if known." }, "provider": { "type": "string", "description": "Provider that produced the reasoning item (e.g., \"openai\")." }, "summary": { "type": "array", "items": { "type": "string" }, "description": "Safe summary text segments curated by the provider. Never includes\nplaintext reasoning content." }, "token_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Per-item reasoning token count, when the provider reports one.", "minimum": 0 }, "turn_id": { "type": "string", "description": "Turn ID this reasoning item belongs to.", "example": "turn_01933b5a00007000800000000000001" } } }, "ReasonRecoveredData": { "type": "object", "description": "Data for the `reason.recovered` event (EVE-532).\n\nEmitted by `ReasonAtom` when it detects an in-flight partial assistant\nmessage from a previous worker execution and applies the ContinuePartial\nrecovery policy.", "required": [ "turn_id", "mode", "accumulated_len" ], "properties": { "accumulated_len": { "type": "integer", "description": "Character length of the persisted accumulated text.", "minimum": 0 }, "mode": { "$ref": "#/components/schemas/RecoveryMode", "description": "Recovery action taken." }, "turn_id": { "type": "string", "description": "Turn ID the partial belonged to.", "example": "turn_01933b5a00007000800000000000001" } } }, "ReasonStartedData": { "type": "object", "description": "Data for reason.started event", "required": [ "harness_id" ], "properties": { "agent_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/agentId", "description": "Agent ID being used (optional)" } ] }, "harness_id": { "$ref": "#/components/schemas/harnessId", "description": "Harness ID being used" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelMetadata", "description": "Metadata about the model being used" } ] } } }, "ReasonThinkingCompletedData": { "type": "object", "description": "Data for reason.thinking.completed event\n\nEmitted when extended thinking completes and the model transitions\nto producing the final response. Contains the complete thinking content.", "required": [ "turn_id", "thinking" ], "properties": { "thinking": { "type": "string", "description": "Complete thinking content" }, "turn_id": { "type": "string", "description": "Turn ID this thinking belongs to", "example": "turn_01933b5a00007000800000000000001" } } }, "ReasonThinkingDeltaData": { "type": "object", "description": "Data for reason.thinking.delta event (extended thinking content from models like Claude)\n\nThis event streams incremental thinking/reasoning content from models that support\nextended thinking mode (e.g., Claude with thinking enabled). The thinking content\nrepresents the model's chain-of-thought reasoning before producing the final response.", "required": [ "turn_id", "delta", "accumulated" ], "properties": { "accumulated": { "type": "string", "description": "Accumulated thinking text so far (convenience for UI)" }, "delta": { "type": "string", "description": "The thinking delta (new thinking text since last delta)" }, "turn_id": { "type": "string", "description": "Turn ID this delta belongs to (for correlation)", "example": "turn_01933b5a00007000800000000000001" } } }, "ReasonThinkingStartedData": { "type": "object", "description": "Data for reason.thinking.started event\n\nEmitted when extended thinking begins during reasoning phase.\nThis signals the model is using chain-of-thought reasoning.\nUI can show a \"thinking\" indicator.", "required": [ "turn_id" ], "properties": { "model": { "type": [ "string", "null" ], "description": "Optional model name being used" }, "turn_id": { "type": "string", "description": "Turn ID this thinking belongs to", "example": "turn_01933b5a00007000800000000000001" } } }, "ReasoningConfig": { "type": "object", "description": "Reasoning configuration for the model", "properties": { "effort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningEffort", "description": "Effort level for reasoning.\n\nTyped rather than free-form: the effort taxonomy is closed, and each\ndriver previously re-parsed the string with its own case handling, which\nlet `minimal` silently mean \"no reasoning\" on budget-based models." } ] } } }, "ReasoningContentPart": { "type": "object", "description": "One provider-issued reasoning artifact, ordered in `Message.content`\nalongside text and tool calls.\n\nOrdering is the point. Providers interleave reasoning with text and tool\ncalls, and every current provider requires its artifacts replayed in the\nposition it issued them: Anthropic verifies each thinking block against its\nown `signature`, OpenAI keys reasoning items by the `item_id` it issued and\nexpects them adjacent to the item they precede, and Gemini binds a\n`thoughtSignature` to a specific function call. A flattened per-message\nfield cannot express any of that, so this is a content part.\n\n`signature` and `encrypted` are opaque provider artifacts. They are carried\nverbatim and never interpreted, never rendered, and never published on an\nAPI surface — see [`ReasoningContentPart::to_public`].", "required": [ "provider" ], "properties": { "bound_tool_call_id": { "type": [ "string", "null" ], "description": "Id of the tool call this artifact is bound to, when the provider scopes\nit that way (Gemini attaches a thought signature to one function call)." }, "encrypted": { "type": [ "string", "null" ], "description": "Provider-encrypted reasoning context (OpenAI `encrypted_content`).\nOpaque." }, "item_id": { "type": [ "string", "null" ], "description": "Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`)." }, "provider": { "type": "string", "description": "Provider that produced this artifact (e.g. `anthropic`, `openai`).\nReplay is only valid against the provider that issued it." }, "signature": { "type": [ "string", "null" ], "description": "Provider signature over this specific block (Anthropic thinking\nsignature, Gemini `thoughtSignature`). Opaque." }, "text": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningText", "description": "Readable reasoning, when the provider exposes any." } ] }, "tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Reasoning tokens attributed to this artifact, when reported.", "minimum": 0 } } }, "ReasoningEffort": { "type": "string", "description": "Reasoning effort level for models that support it", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "ReasoningEffortConfig": { "type": "object", "description": "Reasoning effort configuration for a model", "required": [ "values", "default" ], "properties": { "default": { "$ref": "#/components/schemas/ReasoningEffort", "description": "Default reasoning effort for this model" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/ReasoningEffortValue" }, "description": "Available reasoning effort values for this model" } } }, "ReasoningEffortValue": { "type": "object", "description": "Named reasoning effort value for UI display", "required": [ "value", "name" ], "properties": { "name": { "type": "string", "description": "Display name (e.g., \"Low\", \"Medium\")" }, "value": { "$ref": "#/components/schemas/ReasoningEffort", "description": "The API value (e.g., \"low\", \"medium\")" } } }, "ReasoningState": { "type": "object", "description": "Persisted with assistant messages and native compaction checkpoints.", "required": [ "epoch" ], "properties": { "baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningEffort", "description": "Original request-level effort preserved throughout this epoch." } ] }, "effective": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningEffort", "description": "Effort currently active after ordered configuration updates." } ] }, "epoch": { "type": "string", "description": "A new epoch starts when switching model/provider or entering this mode.", "example": "01933b5a-0000-7000-8000-000000000001" } } }, "ReasoningText": { "oneOf": [ { "type": "object", "description": "Verbatim chain-of-thought exposed by the provider (Anthropic extended\nthinking, Gemini thought parts, Chat Completions `reasoning_content`).", "required": [ "text", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "plain" ] }, "text": { "type": "string" } } }, { "type": "object", "description": "Provider-curated summary segments, not raw chain-of-thought (OpenAI\nResponses `summary_text`). Safe to display; never the model's own words.", "required": [ "parts", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "summary" ] }, "parts": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "description": "The provider withheld the content (Anthropic `redacted_thinking`). The\nartifact must still be replayed verbatim, so the part keeps its\nsignature/encrypted payload while carrying no readable text.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "redacted" ] } } } ], "description": "Readable reasoning text, in the form the provider actually exposes.\n\nProviders differ in *what* they are willing to show, and collapsing that\ndifference loses the one thing a consumer needs to know: whether it is\nlooking at the model's own words or a curated gloss of them." }, "RecoveryMode": { "type": "string", "description": "Recovery mode chosen by the ContinuePartial classifier (EVE-532).", "enum": [ "finalize", "restart" ] }, "ReportColumn": { "type": "object", "description": "One column header in a `ReportResult`. The ordered `columns` list\ndeclares the key set of each row in `rows`.", "required": [ "name", "kind" ], "properties": { "kind": { "$ref": "#/components/schemas/ReportColumnKind", "description": "Whether this column is a grouping `dimension` or an aggregate\n`measure` — the same distinction made on `ReportQuery`." }, "name": { "type": "string", "description": "Column name as it appears in `rows`.", "example": "session_count" } } }, "ReportColumnKind": { "type": "string", "description": "Whether a `ReportColumn` is a grouping dimension or an aggregate measure.", "enum": [ "dimension", "measure" ] }, "ReportExport": { "type": "object", "description": "Serialized export of a report's data, ready to stream to a caller as a\ndownload. Carries the rendered payload plus the MIME/filename metadata\na client needs to save it.", "required": [ "format", "filename", "content_type", "content", "as_of" ], "properties": { "as_of": { "type": "string", "format": "date-time", "description": "Timestamp the underlying data was materialized (RFC 3339). Useful for \"as of\" footers." }, "content": { "type": "string", "description": "Serialized payload as a UTF-8 string. Caller streams this to the client." }, "content_type": { "type": "string", "description": "MIME type matching `format` (`text/csv` for CSV exports)." }, "filename": { "type": "string", "description": "Suggested filename for the download (includes the extension matching `format`)." }, "format": { "$ref": "#/components/schemas/ReportExportFormat", "description": "Export format (currently `csv`)." }, "freshness_lag_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "How stale the data is relative to `now()`, in milliseconds. `None` when freshness can't be determined." } } }, "ReportExportFormat": { "type": "string", "description": "Output format for a report export. `Csv` emits a header row plus one\nrow per result; `Json` emits an envelope with the same shape as\n`ReportResult`.", "enum": [ "csv", "json" ] }, "ReportFilter": { "type": "object", "description": "One predicate filter applied to the dataset before aggregation.\nCombined with other filters via logical AND.", "required": [ "field", "op", "value" ], "properties": { "field": { "type": "string", "description": "Field to filter on. Must be a filter field exposed by the dataset (see `filter_fields` in the catalog).", "example": "status" }, "op": { "$ref": "#/components/schemas/ReportFilterOp", "description": "Comparison operator. Determines the expected shape of `value`\n(scalar for `eq`/`neq`/`gt`/`gte`/`lt`/`lte`, array for `in`)." }, "value": { "description": "Comparison value. Type depends on `op`: a scalar for `eq`/`neq`/`gt`/`gte`/`lt`/`lte`,\nan array for `in`. Example for `op = in`: `[\"completed\", \"failed\"]`." } } }, "ReportFilterOp": { "type": "string", "description": "Comparison operator used in a `ReportFilter`. The `In` variant takes a\nJSON array as its value; all others take a scalar.", "enum": [ "eq", "neq", "in", "gt", "gte", "lt", "lte" ] }, "ReportOrderBy": { "type": "object", "description": "One sort clause applied to the aggregated result. Either `dimension`\nOR `measure` is set (mutually exclusive), never both.", "properties": { "dimension": { "type": [ "string", "null" ], "description": "Dimension name to sort by. Mutually exclusive with `measure`.", "example": "org_id" }, "direction": { "$ref": "#/components/schemas/ReportOrderDirection", "description": "Sort direction (`asc` or `desc`). Defaults to `asc`." }, "measure": { "type": [ "string", "null" ], "description": "Measure name to sort by. Mutually exclusive with `dimension`.", "example": "session_count" } } }, "ReportOrderDirection": { "type": "string", "description": "Sort direction for a `ReportOrderBy` clause.", "enum": [ "asc", "desc" ] }, "ReportQuery": { "type": "object", "description": "Semantic query a caller submits to the reporting layer. The backend\ncompiles this to its native query language, scopes it to the calling\norg, and returns a `ReportResult`.", "required": [ "dataset", "time_range" ], "properties": { "dataset": { "type": "string", "description": "Dataset name to query (see `GET /v1/reports/catalog` for the list of available datasets).", "example": "sessions" }, "dimensions": { "type": "array", "items": { "type": "string" }, "description": "Columns to group by. Empty list returns one aggregate row.", "example": [ "status" ] }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/ReportFilter" }, "description": "Predicate filters applied before aggregation." }, "limit": { "type": "integer", "format": "int32", "description": "Maximum number of rows to return (defaults to 100).", "example": 100, "minimum": 0 }, "measures": { "type": "array", "items": { "type": "string" }, "description": "Aggregations to compute (count, sum, avg, etc.). Empty list returns row counts only.", "example": [ "session_count", "avg_duration_ms" ] }, "order_by": { "type": "array", "items": { "$ref": "#/components/schemas/ReportOrderBy" }, "description": "Sort spec applied after aggregation. Empty list yields unspecified order." }, "time_range": { "$ref": "#/components/schemas/ReportTimeRange", "description": "Time window for the query. The dataset selects which timestamp column the range applies to." } } }, "ReportResult": { "type": "object", "description": "Materialized result of a report query — column metadata, rows, and the\nfreshness of the underlying data.", "required": [ "as_of", "columns", "rows" ], "properties": { "as_of": { "type": "string", "format": "date-time", "description": "Timestamp the underlying data was materialized (RFC 3339). Useful as\nan \"as of\" footer when rendering — distinct from when the query ran." }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ReportColumn" }, "description": "Column metadata in the same order as the entries of each row in\n`rows`. Use the `kind` field to tell dimensions from measures." }, "freshness_lag_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "How stale the data is relative to the server's wall clock at query\ntime, in milliseconds. `None` when freshness can't be determined\n(e.g. backends that don't track projector lag)." }, "rows": { "type": "array", "items": {}, "description": "Result rows. Each row is a JSON object keyed by column name; cell\ntypes match the underlying dataset (numbers for measures, strings\nor numbers for dimensions). Length is capped by `ReportQuery.limit`." } } }, "ReportTimeRange": { "type": "object", "description": "Half-open time window applied to the dataset's primary timestamp column\nduring a report query. `from` is inclusive, `to` is exclusive.", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window (RFC 3339, inclusive).", "example": "2026-04-24T00:00:00Z" }, "to": { "type": "string", "format": "date-time", "description": "End of the window (RFC 3339, exclusive).", "example": "2026-05-24T00:00:00Z" } } }, "ReportingBackfillRequest": { "type": "object", "description": "Request body for the `reporting_backfill` operation — enqueues source\nrows into the reporting outbox for the projector to re-materialize.", "properties": { "limit": { "type": "integer", "format": "int64", "description": "Maximum number of outbox rows to enqueue across all source types. Defaults to 1000.", "example": 5000 } } }, "ReportingBackfillResult": { "type": "object", "description": "Result of a `reporting_backfill` call — per-source counts of outbox rows\nenqueued for re-projection.", "required": [ "enqueued", "events", "sessions", "llm_generations", "usage_ledger" ], "properties": { "enqueued": { "type": "integer", "format": "int64", "description": "Total number of outbox rows enqueued across all source types." }, "events": { "type": "integer", "format": "int64", "description": "Number of `event` outbox rows enqueued." }, "llm_generations": { "type": "integer", "format": "int64", "description": "Number of `llm_generation` outbox rows enqueued." }, "sessions": { "type": "integer", "format": "int64", "description": "Number of `session` outbox rows enqueued." }, "usage_ledger": { "type": "integer", "format": "int64", "description": "Number of `usage_ledger` outbox rows enqueued." } } }, "ReportingDiagnostics": { "type": "object", "description": "Point-in-time health snapshot of the reporting layer — projector\nfreshness plus outbox processing health. Returned from\n`GET /v1/reports/admin/diagnostics`.", "required": [ "generated_at", "projector_lag", "outbox" ], "properties": { "generated_at": { "type": "string", "format": "date-time", "description": "Server-side wall-clock timestamp when this snapshot was assembled\n(RFC 3339). Use as the \"as-of\" for any displayed lag metrics." }, "outbox": { "$ref": "#/components/schemas/ReportingOutboxDiagnostics", "description": "Reporting outbox health — counts of pending/processing/failed/\ncompleted rows plus a sample of the most recent failures." }, "projector_lag": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetProjectorLag" }, "description": "Per-dataset projector freshness. One entry per active reporting\ndataset; missing datasets mean the projector hasn't produced any\nrows yet." } } }, "ReportingOutboxDiagnostics": { "type": "object", "description": "Aggregate health of the reporting outbox — the queue of source rows\nwaiting to be projected into fact tables.", "required": [ "pending", "processing", "failed", "completed", "failed_rows" ], "properties": { "completed": { "type": "integer", "format": "int64", "description": "Outbox rows that have completed processing successfully." }, "failed": { "type": "integer", "format": "int64", "description": "Outbox rows that have failed (exceeded retry limit)." }, "failed_rows": { "type": "array", "items": { "$ref": "#/components/schemas/FailedReportingOutboxRow" }, "description": "Sample of the most recent failed rows for operator inspection." }, "oldest_pending_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the oldest `pending` row (RFC 3339). `None` if no rows are pending." }, "pending": { "type": "integer", "format": "int64", "description": "Outbox rows waiting to be claimed by a projector." }, "processing": { "type": "integer", "format": "int64", "description": "Outbox rows currently being processed." } } }, "ResolveOrgResponse": { "type": "object", "description": "Response body for the `resolve_org` operation.", "required": [ "org_id", "org_name" ], "properties": { "org_id": { "type": "string", "description": "Public ID of the organization that owns the resource." }, "org_name": { "type": "string", "description": "Organization name (for UX messaging)." } } }, "ResourceConfigResponse": { "type": "object", "description": "Response type for per-resource config endpoints.\n\nEvery resource exposes `GET /v1/{resource}/config` returning this type.\nUI uses it to gate controls (create/edit/delete buttons, admin panels).", "required": [ "policies" ], "properties": { "policies": { "type": "object", "description": "Map of policy ID → whether the caller satisfies it.", "additionalProperties": { "type": "boolean" }, "propertyNames": { "type": "string" } } } }, "ResourceStats": { "type": "object", "description": "Response body for resource stats.", "required": [ "session_count", "active_session_count", "idle_session_count", "started_session_count", "waiting_for_tool_results_session_count", "execution_count", "total_session_duration_ms", "total_input_tokens", "total_output_tokens", "total_cache_read_tokens", "total_cache_creation_tokens", "total_actual_cost_usd", "total_estimated_cost_usd", "total_cost_usd" ], "properties": { "active_session_count": { "type": "integer", "format": "int64", "description": "Sessions in a running state right now.", "example": 7, "minimum": 0 }, "avg_session_duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Average session duration in milliseconds. `None` when `session_count` is 0.", "example": 20858, "minimum": 0 }, "execution_count": { "type": "integer", "format": "int64", "description": "Total number of agent executions (turns) recorded across all sessions for this resource.", "example": 14206, "minimum": 0 }, "first_session_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the first session for this resource (RFC 3339). `None` if no sessions exist.", "example": "2026-01-04T11:23:00Z" }, "idle_session_count": { "type": "integer", "format": "int64", "description": "Sessions in an idle state right now (created but no recent activity).", "example": 23, "minimum": 0 }, "last_execution_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent execution (turn) for this resource (RFC 3339). `None` if no executions exist.", "example": "2026-05-27T15:24:42Z" }, "last_session_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent session for this resource (RFC 3339). `None` if no sessions exist.", "example": "2026-05-27T15:24:00Z" }, "session_count": { "type": "integer", "format": "int64", "description": "Total number of sessions ever created for this resource.", "example": 1842, "minimum": 0 }, "started_session_count": { "type": "integer", "format": "int64", "description": "Sessions that have started at least one turn.", "example": 1810, "minimum": 0 }, "total_actual_cost_usd": { "type": "number", "format": "double", "description": "Cumulative provider-reported actual cost in USD across all sessions\n(e.g. OpenRouter's `usage.cost`). Excludes generations with no reported cost.", "example": 31.07 }, "total_cache_creation_tokens": { "type": "integer", "format": "int64", "description": "Cumulative cache-write tokens across all sessions (charged when first writing a cache entry).", "example": 412005, "minimum": 0 }, "total_cache_read_tokens": { "type": "integer", "format": "int64", "description": "Cumulative cache-read tokens across all sessions (where the provider supports prompt caching).", "example": 5234122, "minimum": 0 }, "total_cost_usd": { "type": "number", "format": "double", "description": "Cumulative best-effort cost in USD across all sessions: actual provider\ncost where reported, otherwise the price-table estimate. Actual takes priority.", "example": 42.18 }, "total_estimated_cost_usd": { "type": "number", "format": "double", "description": "Cumulative price-table estimated cost in USD across all sessions.\nExcludes generations with no profile cost data.", "example": 40.55 }, "total_input_tokens": { "type": "integer", "format": "int64", "description": "Cumulative LLM input tokens billed across all sessions.", "example": 18457321, "minimum": 0 }, "total_output_tokens": { "type": "integer", "format": "int64", "description": "Cumulative LLM output tokens billed across all sessions.", "example": 2184109, "minimum": 0 }, "total_session_duration_ms": { "type": "integer", "format": "int64", "description": "Cumulative session wall-clock duration in milliseconds across all sessions.", "example": 38421500, "minimum": 0 }, "waiting_for_tool_results_session_count": { "type": "integer", "format": "int64", "description": "Sessions currently paused waiting for client-side tool results.", "example": 2, "minimum": 0 } } }, "ResumeSessionResponse": { "type": "object", "description": "Result of resuming budgets paused for a session.", "required": [ "resumed_budgets", "session_id" ], "properties": { "resumed_budgets": { "type": "integer", "minimum": 0 }, "session_id": { "type": "string" } } }, "RiskLevel": { "type": "string", "description": "Risk classification for capabilities (TM-AGENT-005).\n\nUsed to enforce approval requirements when assigning capabilities.", "enum": [ "low", "medium", "high" ], "example": "low" }, "RollbackAgentVersionRequest": { "type": "object", "description": "Request body for the `rollback_agent_version` operation.", "properties": { "save_version": { "type": "boolean", "description": "When true, snapshot the current agent state as a new version before rolling back.\nUse this to preserve the in-flight work alongside the recovery point.", "example": true }, "summary": { "type": [ "string", "null" ], "description": "Free-text summary attached to the rollback. Shown in the version timeline.", "example": "Reverting refund-window change — false positives in production." } } }, "RuntimeMessage": { "type": "object", "description": "A message in the conversation", "required": [ "id", "role", "content", "created_at" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" }, "description": "Message content as array of content parts (text, images, tool calls, tool results)" }, "controls": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Controls", "description": "Runtime controls (model, reasoning, etc.)" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the message was created" }, "external_actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalActor", "description": "External actor identity (for messages from external channels like Slack)" } ] }, "id": { "type": "string", "description": "Unique message ID (format: message_{32-hex})", "example": "message_01933b5a00007000800000000000001" }, "metadata": { "type": [ "object", "null" ], "description": "Message-level metadata" }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExecutionPhase", "description": "Execution phase for this message.\n\nHelps LLMs distinguish between intermediate working commentary and completed\nanswers in multi-step tool-calling flows. Only set on agent (assistant) messages.\nProviders with native phase support (OpenAI GPT-5.x) send this value in the API\nrequest; others derive it from state but don't send it to the provider." } ] }, "phase_source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PhaseSource", "description": "Whether [`Self::phase`] was reported by the provider or inferred from\ntool-call presence. A derived phase carries no information beyond\n\"this message called tools\", so consumers that need a real\nclassification must be able to tell the two apart." } ] }, "role": { "$ref": "#/components/schemas/RuntimeMessageRole", "description": "Message role" } } }, "RuntimeMessageRole": { "type": "string", "description": "Message role in the conversation", "enum": [ "system", "user", "agent", "tool_result" ] }, "SavedReport": { "type": "object", "description": "A user-saved report definition — a named, persistable wrapper around a\n`ReportQuery` with optional dashboard placement metadata.", "required": [ "id", "name", "query", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "dashboard": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SavedReportDashboardMetadata", "description": "Optional dashboard placement metadata. `None` means the report is\n\"library-only\" and not pinned to a dashboard layout." } ] }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages." }, "id": { "type": "string", "format": "uuid", "description": "UUID of the saved report." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "query": { "$ref": "#/components/schemas/ReportQuery", "description": "The query this report executes when run or exported. Same shape as the\n`body` of `POST /v1/reports/query` — see `ReportQuery` for the field\nbreakdown." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, "SavedReportDashboardMetadata": { "type": "object", "description": "Dashboard placement metadata attached to a `SavedReport`. Captures how\nand where to render the report in the operator dashboard UI.", "properties": { "chart_type": { "type": [ "string", "null" ], "description": "Rendering hint for the UI (e.g. `\"line\"`, `\"bar\"`, `\"table\"`,\n`\"big_number\"`). Free-form string — the server doesn't enforce a\nclosed set so new chart types can roll out client-side first." }, "position": { "type": [ "integer", "null" ], "format": "int32", "description": "Sort key within `section`. Lower values render first. `None` means\n\"place at the end\"." }, "section": { "type": [ "string", "null" ], "description": "Dashboard section/group this report belongs to (free-form bucket name\nlike `\"Operations\"` or `\"Finance\"`). Used to cluster related reports\nin the UI." }, "title": { "type": [ "string", "null" ], "description": "Human-readable title. Safe to render in user-facing messages." } } }, "ScheduleExecutionResponse": { "type": "object", "description": "Schedule execution response", "required": [ "id", "schedule_id", "scheduled_at", "started_at", "status", "created_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource completed, if any (RFC 3339).", "example": "2026-05-25T02:00:12Z" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339).", "example": "2026-05-25T02:00:00Z" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int32", "description": "Total execution duration in milliseconds (`completed_at - started_at`). `None` while still running.", "example": 11000 }, "error": { "type": [ "string", "null" ], "description": "Human-readable error message, populated when this resource is in a failed state.", "example": "workflow.exec.timeout: activity exceeded 30s budget" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the schedule execution.", "example": "01933b5b-0000-7000-8000-000000000001" }, "schedule_id": { "type": "string", "format": "uuid", "description": "UUID of the owning schedule.", "example": "01933b5a-0000-7000-8000-000000000001" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource is scheduled to run (RFC 3339).", "example": "2026-05-25T02:00:00Z" }, "started_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource started, if any (RFC 3339).", "example": "2026-05-25T02:00:01Z" }, "status": { "type": "string", "description": "Current lifecycle status (`pending`, `running`, `completed`, `failed`, `skipped`).", "example": "completed" }, "task_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Durable task's identifier.", "example": "01933b5d-0000-7000-8000-000000000001" }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Durable workflow's identifier.", "example": "01933b5c-0000-7000-8000-000000000001" } } }, "ScheduleExecutionsListResponse": { "type": "object", "description": "Schedule executions list response", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleExecutionResponse" }, "description": "Page of items returned by this query." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages.", "example": 142, "minimum": 0 } } }, "ScheduleResponse": { "type": "object", "description": "Schedule response", "required": [ "id", "name", "cron_expression", "timezone", "target", "enabled", "catch_up_missed", "created_at", "updated_at" ], "properties": { "catch_up_missed": { "type": "boolean", "description": "When `true`, missed fires (while the scheduler was down, paused, or unreachable) are queued and run after recovery, subject to `max_catch_up`.", "example": false }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339).", "example": "2026-05-01T12:00:00Z" }, "cron_expression": { "type": "string", "description": "Cron expression in the standard `min hour day-of-month month day-of-week` form (6 fields with seconds optional). Evaluated in `timezone`.", "example": "0 2 * * *" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Fires the support-triage agent every night at 02:00 UTC" }, "enabled": { "type": "boolean", "description": "When `false`, the schedule is paused — kept in storage but never fires until re-enabled.", "example": true }, "id": { "type": "string", "format": "uuid", "description": "UUID of the schedule.", "example": "01933b5a-0000-7000-8000-000000000001" }, "last_triggered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent fire (RFC 3339). `None` if never triggered.", "example": "2026-05-25T02:00:00Z" }, "max_catch_up": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of missed fires to replay when `catch_up_missed` is `true`. Older missed fires are dropped. `None` means no cap.", "example": 3, "minimum": 0 }, "max_concurrent": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum number of overlapping executions allowed. `None` means no limit beyond the worker pool's concurrency.", "example": 1, "minimum": 0 }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "nightly-triage" }, "next_trigger_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the next scheduled fire (RFC 3339). `None` when the schedule is disabled or the cron expression has no upcoming match.", "example": "2026-05-26T02:00:00Z" }, "retry_policy": { "description": "Optional retry policy for failed runs (provider-specific JSON; see the durable engine's `RetryPolicy`).\nExample: `{\"max_attempts\": 3, \"initial_backoff_secs\": 30, \"backoff_multiplier\": 2.0}`." }, "target": { "$ref": "#/components/schemas/ScheduleTargetResponse", "description": "What the schedule invokes when it fires (a session, an agent, an app channel, etc.)." }, "timezone": { "type": "string", "description": "IANA timezone name used to interpret `cron_expression` (e.g. `UTC`, `America/New_York`).", "example": "UTC" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339).", "example": "2026-05-20T12:00:00Z" } } }, "ScheduleStatsResponse": { "type": "object", "description": "Schedule stats response", "required": [ "total_executions", "successful_executions", "failed_executions", "skipped_executions" ], "properties": { "avg_duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Average execution duration in milliseconds across `total_executions`. `None` when no executions exist yet.", "example": 8421, "minimum": 0 }, "failed_executions": { "type": "integer", "format": "int64", "description": "Count of executions that ended in failure (after exhausting retries).", "example": 3, "minimum": 0 }, "last_execution_status": { "type": [ "string", "null" ], "description": "Status of the most recent execution (one of the `ScheduleExecutionResponse.status` values:\n`pending`, `running`, `completed`, `failed`, `skipped`). `None` if the schedule has never fired.", "example": "completed" }, "skipped_executions": { "type": "integer", "format": "int64", "description": "Count of fires that were intentionally skipped (e.g. blocked by `max_concurrent` or disabled mid-fire).", "example": 2, "minimum": 0 }, "successful_executions": { "type": "integer", "format": "int64", "description": "Count of executions that completed successfully.", "example": 137, "minimum": 0 }, "total_executions": { "type": "integer", "format": "int64", "description": "Total number of executions recorded for this schedule (sum of successful + failed + skipped).", "example": 142, "minimum": 0 } } }, "ScheduleTarget": { "type": "object", "description": "Target for a schedule - either a workflow or activity", "required": [ "type", "name" ], "properties": { "input": { "description": "Input JSON for the workflow/activity" }, "name": { "type": "string", "description": "Workflow type name or activity type name", "example": "session.run" }, "type": { "type": "string", "description": "Target type: \"workflow\" or \"activity\"", "example": "workflow" } }, "example": { "input": { "session_id": "session_01933b5a00007000800000000000001" }, "name": "session.run", "type": "workflow" } }, "ScheduleTargetResponse": { "type": "object", "description": "Schedule target response", "required": [ "type", "name", "input" ], "properties": { "input": { "type": "object", "description": "Input JSON payload passed to the workflow/activity on each fire.\nExample: `{\"session_id\": \"session_01933b5a000070008000000000000001\"}`." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages.", "example": "session.run" }, "type": { "type": "string", "description": "Target type discriminator (`workflow` or `activity`).", "example": "workflow" } } }, "ScheduleTriggerConfig": { "type": "object", "description": "Typed configuration for a `Schedule` trigger.\n\n`message` is also the template body. `{{path.to.value}}` placeholders are\nexpanded at invocation time. Mirrors `app::ScheduleChannelConfig`.", "required": [ "cron_expression", "message" ], "properties": { "cron_expression": { "type": "string", "description": "Cron expression that drives the durable schedule." }, "message": { "type": "string", "description": "Message content or template sent when the schedule fires." }, "session_mode": { "$ref": "#/components/schemas/SessionBinding", "description": "Whether invocations reuse a stable session or create a new one." }, "timezone": { "type": "string", "description": "IANA timezone identifier for cron evaluation." } } }, "SchedulesListResponse": { "type": "object", "description": "Schedules list response", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleResponse" }, "description": "Page of items returned by this query." }, "total": { "type": "integer", "format": "int64", "description": "Total number of items matching the query, across all pages.", "example": 17, "minimum": 0 } } }, "SchemaResponse": { "type": "object", "description": "Schema response for a database.", "required": [ "database", "tables" ], "properties": { "database": { "type": "string" }, "tables": { "type": "array", "items": {} } } }, "SecretInfo": { "type": "object", "description": "Secret entry info (name and timestamps only, no value)", "required": [ "name", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "description": "When the secret was created" }, "name": { "type": "string", "description": "The secret name" }, "updated_at": { "type": "string", "description": "When the secret was last updated" } } }, "SendSignalRequest": { "type": "object", "description": "Request to send a signal to a workflow", "required": [ "signal_type" ], "properties": { "payload": { "description": "Signal payload (workflow-specific JSON, any shape; defaults to `null` when omitted).\nExample: `{\"approved\": true, \"approver\": \"user_01933b5a00007000800000000000001\"}`." }, "signal_type": { "type": "string", "description": "Signal name. Must match a signal the running workflow listens for.", "example": "user_response_received" } } }, "Session": { "type": "object", "description": "Session - instance of agentic loop execution.\nA session represents a single conversation with an agent.", "required": [ "id", "organization_id", "workspace_id", "harness_id", "owner_principal_id", "status", "created_at", "updated_at" ], "properties": { "active_schedule_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of active (enabled) schedules for this session.\nPopulated when the session is fetched for API responses.", "example": 2, "minimum": 0 }, "activity": { "$ref": "#/components/schemas/SessionActivity", "description": "Outcome-oriented status derived from `status` and the last turn result.\nThis is the value the sessions list groups by and the facet rail counts." }, "agent_id": { "type": [ "string", "null" ], "description": "ID of the agent working in this session (format: agent_{32-hex}). Optional.", "example": "agent_01933b5a00007000800000000000001" }, "agent_identity_id": { "type": [ "string", "null" ], "description": "Optional resident agent identity for unattended/background execution.", "example": "identity_01933b5a00007000800000000000001" }, "agent_version_id": { "type": [ "string", "null" ], "description": "Immutable agent version captured when the session was created or rebound.", "example": "agentver_01933b5a00007000800000000000001" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When this session was archived; `None` means active. Archived sessions\nare hidden from default list results and shown by opting in\n(`include_archived=true`). Unlike `is_pinned`, archive is a property of\nthe session itself rather than of the viewer.", "example": "2026-05-25T10:14:32Z" }, "blueprint_config": { "type": [ "object", "null" ], "description": "Validated config passed by host at blueprint spawn time.\nExample: `{\"target_repo\": \"acme/everruns\"}`." }, "blueprint_id": { "type": [ "string", "null" ], "description": "Blueprint ID. When set, reason_activity and act_activity build RuntimeAgent\nfrom the blueprint definition instead of from harness_id/agent_id.", "example": "blueprint_research_pack" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Session-level capabilities (additive to agent capabilities).\nApplied after agent capabilities when building RuntimeAgent." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was created.", "example": "2026-05-25T10:00:00Z" }, "effective_owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Effective human owner summary." } ] }, "event_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Total events recorded for this session (EVE-868). Read from the\ndenormalized `sessions.event_count` counter rather than counted, so the\nsession detail tab bar costs no extra scan over `events`.\n`None` on payloads built outside the database read path.", "example": 42, "minimum": 0 }, "features": { "type": "array", "items": { "type": "string" }, "description": "Aggregated UI features from all active capabilities (harness + agent + session).\nComputed at read time from the capability registry.\nKnown features: \"file_system\", \"schedules\", \"secrets\", \"key_value\",\n\"sql_database\", \"leased_resources\".", "example": [ "file_system", "secrets" ] }, "file_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Non-directory files in this session's workspace (EVE-868). Read from\n`workspaces.file_count`. Counts persisted files only: capability-provided\nvirtual mounts are served from memory and are not included.", "example": 6, "minimum": 0 }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the session finished (completed or failed).", "example": "2026-05-25T10:14:32Z" }, "forked_from_sequence": { "type": [ "integer", "null" ], "format": "int32", "description": "Parent event sequence the fork was taken at (the fork point). NULL unless\nthis session is a fork.", "example": 42 }, "forked_from_session_id": { "type": [ "string", "null" ], "description": "Session this one was forked from. NULL for sessions that were not forked.\nDistinct from `parent_session_id` (subagent nesting): forking is a\nuser-initiated \"branch from here\" relationship." }, "goal": { "type": [ "string", "null" ], "description": "Session objective visible to the runtime agent at system-prompt level.", "example": "Investigate the queue latency regression" }, "harness_id": { "type": "string", "description": "ID of the harness for this session (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "hints": { "type": [ "object", "null" ], "description": "Session-level client hints — arbitrary key-value pairs declared by the\nclient at session creation time. These are defaults for every turn;\nper-message `controls.hints` override these key-by-key (shallow merge).\n\nExamples: `{\"setup_connection\": true, \"rich_media\": true}`", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Unique identifier for the session (format: session_{32-hex}).", "example": "session_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Session-level initial files (additive to agent initial_files).\nFiles with matching paths override agent/harness files; new paths are appended." }, "is_pinned": { "type": [ "boolean", "null" ], "description": "Whether this session is pinned by the current user.\nOnly populated when the request has an authenticated user context.", "example": false }, "locale": { "type": [ "string", "null" ], "description": "Locale for localized agent behavior and formatting (BCP 47, e.g. `uk-UA`).", "example": "en-US" }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this session.", "example": 50, "minimum": 0 }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this session only." }, "model_id": { "type": [ "string", "null" ], "description": "LLM model ID to use for this session (format: model_{32-hex}).\nOverrides the agent's default model if set.", "example": "model_01933b5a00007000800000000000001" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs this session can reach.\nMerged with harness and agent layers (allowed: intersect, blocked: union)." } ] }, "organization_id": { "type": "string", "description": "Organization this session belongs to (format: org_{32-hex}).", "example": "org_00000000000000000000000000000001" }, "output_preview": { "type": [ "string", "null" ], "description": "Preview text from the last assistant response (truncated).", "example": "Here is a Q3 plan covering the three pillars we discussed..." }, "owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Owning principal summary." } ] }, "owner_principal_id": { "type": "string", "description": "Owning principal for this session.", "example": "principal_01933b5a000070008000000000000001" }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "parent_session_id": { "type": [ "string", "null" ], "description": "Parent session that spawned this subagent. NULL for top-level sessions.\nUsed to compute governed subagent delegation depth." }, "preview": { "type": [ "string", "null" ], "description": "Preview text from the first user message (truncated).", "example": "Help me draft the Q3 marketing plan" }, "resolved_owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Denormalized effective human owner of the owning principal lineage.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "run_summary": { "type": [ "string", "null" ], "description": "Generated one-sentence description of what the run did, and where it\nfailed (EVE-867). Absent until a terminal turn has been summarised, and\nalways absent for chat threads and for deployments with no utility LLM,\nso a reader must have a fallback rather than treating this as required.", "example": "Ran the nightly report and failed posting it to Slack: channel_not_found." }, "source": { "$ref": "#/components/schemas/SessionSource", "description": "How this session was started. Server-owned for every ingress path." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the session started executing.", "example": "2026-05-25T10:00:01Z" }, "status": { "$ref": "#/components/schemas/SessionStatus", "description": "Current execution status of the session." }, "system_prompt": { "type": [ "string", "null" ], "description": "Session-level system prompt override.\nPrepended to the agent's system prompt when building RuntimeAgent." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering sessions.", "example": [ "marketing", "q3", "draft" ] }, "task_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Background work owned by this session — subagents, external agents and\nbackground tools (EVE-868). Read from `sessions.task_count`. This is\nwhat the Work tab holds; `active_schedule_count` describes only the\nschedules it also lists.", "example": 3, "minimum": 0 }, "title": { "type": [ "string", "null" ], "description": "Human-readable title for the session.", "example": "Q3 marketing brief" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools for this session (additive to agent tools)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was last updated.", "example": "2026-05-25T10:14:32Z" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative token usage for all LLM calls in this session." } ] }, "workspace_id": { "type": "string", "description": "Workspace this session is attached to (format: wsp_{32-hex}). Owns the\nsession's virtual filesystem. For the default 1:1 case this mirrors the\nsession id, but clients should read it here rather than deriving it.", "example": "wsp_01933b5a00007000800000000000001" } } }, "SessionActivatedData": { "type": "object", "description": "Data for session.activated event (turn started, session now active)", "required": [ "turn_id", "input_message_id" ], "properties": { "input_message_id": { "type": "string", "description": "Input message ID that triggered the turn", "example": "message_01933b5a00007000800000000000001" }, "turn_id": { "type": "string", "description": "Turn ID that activated the session", "example": "turn_01933b5a00007000800000000000001" } } }, "SessionActivity": { "type": "string", "description": "Outcome-oriented view of a session, as the sessions list and facet rail\npresent it. Derived from the session's execution status plus the outcome of\nits most recent turn — `SessionStatus` alone has no notion of failure.", "enum": [ "running", "paused", "failed", "completed", "idle" ] }, "SessionBinding": { "type": "string", "description": "What identity keys a session, for every exposure and every transport.\n\nOne enum replaces the former `SessionStrategy` (messaging channels) and\n`InvocationSessionMode` (triggers and request/reply endpoints), which asked\nthe same question with disjoint vocabularies and forced every new surface to\npick a side (EVE-1005).\n\n**The serialized values are deliberately the legacy ones.** Every variant\nrenames in Rust but serializes exactly as it did before, with the new name\naccepted as a read alias. Persisted `channel_config` JSONB therefore needs no\nmigration, and the API and UI keep exchanging the values they already do.\nMoving the wire vocabulary is a separate, migration-bearing change.\n\n`Requester` keys on the **transport's own external actor id** — the Slack\nuser id, the Public Chat visitor id — never on an Everruns principal. Those\nactors are unrelated to Everruns accounts (a Public Chat visitor is anonymous\nor Google-signed-in), so there is one consistent answer rather than a split\nvariant: whatever the transport calls the requester, scoped by the\n`{platform}:` tag prefix that already namespaces it.", "enum": [ "per_thread", "per_channel", "per_user", "shared_session", "session_per_invocation" ], "example": "per_thread" }, "SessionContextReport": { "type": "object", "description": "Token-budget report for a session — a model-aware breakdown of the\ncontext window into named sections plus per-source contributions, so\ncallers can answer \"what's filling the context?\" without reverse-\nengineering the prompt assembly.", "required": [ "session_id", "model", "estimated_input_tokens", "sections", "contributions" ], "properties": { "context_window_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Total context window size in tokens for `model`. `None` if the model's profile lacks limits data.", "minimum": 0 }, "contributions": { "type": "array", "items": { "$ref": "#/components/schemas/ContextReportContribution" }, "description": "Per-source token contributions (per-tool, per-capability, per-message) for attribution." }, "cumulative_usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative LLM usage observed across the session so far (token + cost rollup)." } ] }, "estimated_input_tokens": { "type": "integer", "format": "int32", "description": "Estimated number of input tokens consumed by the next generation given the current context.", "minimum": 0 }, "model": { "type": "string", "description": "Model identifier the report's token estimates target (used to scope context-window math)." }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/ContextReportSection" }, "description": "Logical sections of the assembled context (system prompt, tool defs, message history, etc.) for inspection." }, "session_id": { "type": "string", "description": "Prefixed session identifier this report describes." } } }, "SessionEnvironmentResponse": { "type": "object", "description": "The environment a session is running in.", "required": [ "containment", "durability", "capabilities", "resolved_from" ], "properties": { "capabilities": { "$ref": "#/components/schemas/EnvironmentCapabilities" }, "containment": { "$ref": "#/components/schemas/EnvironmentContainment" }, "durability": { "type": "string", "description": "`checkpointed`, `provider_snapshot`, or `none`. Declared per target, so a\nsession on somebody else's machine is never reported as recoverable." }, "resolved_from": { "type": "string", "description": "How this view was produced. `capabilities` means it was derived from the\nsession's effective capability set rather than read from a stored\nenvironment profile." }, "source_capability": { "type": [ "string", "null" ], "description": "Capability that supplied the compute, for operators tracing a surprise." }, "target": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EnvironmentTarget", "description": "Target, absent when the session has no compute at all and only reads and\nwrites files. That is a real configuration, not a misconfiguration." } ] } } }, "SessionFacetCount": { "type": "object", "description": "One bucket of a sessions facet dimension.", "required": [ "value", "count" ], "properties": { "count": { "type": "integer", "format": "int64", "minimum": 0 }, "value": { "type": "string", "description": "The dimension value: an activity, a source, or an agent's public id.", "example": "running" } } }, "SessionFacetsResponse": { "type": "object", "description": "Facet-rail counts and masthead metrics for the sessions surface (EVE-852).\n\nEvery count is aggregated server-side over the same filter predicate as\n`GET /v1/sessions`, so a client never derives them by paging the list. Each\nfacet dimension is counted with the other filters applied but its own\nselection excluded, which is what lets the rail offer multi-select.", "required": [ "total", "by_activity", "by_source", "by_agent", "active_now", "failed_today", "p95_duration_ms", "tokens_today" ], "properties": { "active_now": { "type": "integer", "format": "int64", "description": "Sessions executing a turn or awaiting client tool results right now.", "minimum": 0 }, "by_activity": { "type": "array", "items": { "$ref": "#/components/schemas/SessionFacetCount" }, "description": "Counts per derived activity (`running`, `paused`, `failed`,\n`completed`, `idle`)." }, "by_agent": { "type": "array", "items": { "$ref": "#/components/schemas/SessionFacetCount" }, "description": "Counts per agent, keyed by the agent's public id. Sessions with no\nagent are omitted." }, "by_source": { "type": "array", "items": { "$ref": "#/components/schemas/SessionFacetCount" }, "description": "Counts per session source." }, "failed_today": { "type": "integer", "format": "int64", "description": "Sessions whose most recent turn failed or was cancelled today (UTC).", "minimum": 0 }, "p95_duration_ms": { "type": "integer", "format": "int64", "description": "95th percentile session duration over the filtered set, milliseconds.", "minimum": 0 }, "tokens_today": { "type": "integer", "format": "int64", "description": "Tokens consumed by sessions created today (UTC).", "minimum": 0 }, "total": { "type": "integer", "format": "int64", "description": "Sessions matching every applied filter.", "minimum": 0 } } }, "SessionFile": { "type": "object", "description": "Complete file with content", "required": [ "id", "session_id", "path", "name", "is_directory", "is_readonly", "size_bytes", "created_at", "updated_at" ], "properties": { "content": { "type": [ "string", "null" ], "description": "File content. Encoding is controlled by the `encoding` field: plain UTF-8 text for `text`, base64-encoded bytes for `base64`. `None` for directories and when this is a metadata-only listing." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this entry was created (RFC 3339)." }, "encoding": { "type": "string", "description": "Content encoding for the `content` field: `text` (UTF-8) or `base64` (binary)." }, "id": { "type": "string", "format": "uuid", "description": "Internal database UUID for this file entry." }, "is_directory": { "type": "boolean", "description": "`true` when this entry represents a directory; `false` for a regular file." }, "is_readonly": { "type": "boolean", "description": "Whether the entry was marked read-only at creation. Read-only entries cannot be edited or deleted by the session." }, "name": { "type": "string", "description": "File or directory name (the last segment of `path`)." }, "path": { "type": "string", "description": "Absolute path within the session workspace (e.g. `/notes.md`)." }, "session_id": { "type": "string", "format": "uuid", "description": "UUID of the owning session." }, "size_bytes": { "type": "integer", "format": "int64", "description": "File size in bytes. `0` for directories." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this entry was last updated (RFC 3339)." } } }, "SessionIdledData": { "type": "object", "description": "Data for session.idled event (turn completed, session now idle)", "required": [ "turn_id" ], "properties": { "iterations": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of iterations in the completed turn", "minimum": 0 }, "turn_id": { "type": "string", "description": "Turn ID that just completed", "example": "turn_01933b5a00007000800000000000001" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative token usage for the session at this point" } ] } } }, "SessionModelChangedData": { "type": "object", "description": "Data for `session.model.changed`.\n\nNames are the provider's own model identifiers, captured at emission time so\nthe transcript stays readable after a model is renamed or removed from the\norganization. Clients that still have the model may prefer its display name.", "required": [ "model_id", "model_name" ], "properties": { "model_id": { "type": "string", "description": "Model selected for the next turn.", "example": "model_01933b5a00007000800000000000002" }, "model_name": { "type": "string", "description": "Name of the selected model, captured at emission time." }, "previous_model_id": { "type": [ "string", "null" ], "description": "Model used before the switch. `None` when the previous turn ran on an\ninherited default that the emitter could not name.", "example": "model_01933b5a00007000800000000000001" }, "previous_model_name": { "type": [ "string", "null" ], "description": "Name of the previous model, captured at emission time." } } }, "SessionParticipant": { "type": "object", "description": "Session participant - an agent or user that has joined a session.", "required": [ "id", "session_id", "kind", "principal_id", "role", "joined_at" ], "properties": { "agent_id": { "type": [ "string", "null" ], "description": "Present for agent participants.", "example": "agent_01933b5a00007000800000000000001" }, "agent_version_id": { "type": [ "string", "null" ], "description": "Immutable agent version captured for an agent participant when known.", "example": "agentver_01933b5a00007000800000000000001" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable name captured for this participant." }, "id": { "type": "string", "description": "Unique identifier for the participant row (format: part_{32-hex}).", "example": "part_01933b5a00007000800000000000001" }, "joined_at": { "type": "string", "format": "date-time" }, "kind": { "$ref": "#/components/schemas/SessionParticipantKind" }, "left_at": { "type": [ "string", "null" ], "format": "date-time" }, "principal_id": { "type": "string", "description": "Principal that joined the session.", "example": "principal_01933b5a000070008000000000000001" }, "role": { "$ref": "#/components/schemas/SessionParticipantRole" }, "session_id": { "type": "string", "description": "Session this participant belongs to.", "example": "session_01933b5a00007000800000000000001" } } }, "SessionParticipantKind": { "type": "string", "description": "Kind of actor participating in a session.", "enum": [ "agent", "user" ] }, "SessionParticipantRole": { "type": "string", "description": "Role a participant has inside a session.", "enum": [ "host", "member" ] }, "SessionRef": { "type": "object", "required": [ "session_id", "status" ], "properties": { "created_session": { "type": [ "boolean", "null" ] }, "session_id": { "type": "string" }, "status": { "type": "string" } } }, "SessionResolvedModelResponse": { "type": "object", "description": "The model the runtime will use when a turn has no per-message override.", "properties": { "model_id": { "type": [ "string", "null" ] } } }, "SessionResourceEntry": { "type": "object", "description": "A resource registered in the session resource registry.", "required": [ "resource_id", "session_id", "kind", "display_name", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "display_name": { "type": "string", "description": "Human-readable label." }, "kind": { "type": "string", "description": "Resource kind: \"sandbox\", \"subagent\", \"browser_session\", etc." }, "metadata": { "description": "Kind-specific non-secret metadata." }, "resource_id": { "type": "string", "description": "Caller-provided stable ID (unique per session)." }, "session_id": { "type": "string", "description": "Parent session." }, "status": { "$ref": "#/components/schemas/SessionResourceStatus", "description": "Lifecycle status." }, "updated_at": { "type": "string", "format": "date-time" } } }, "SessionResourceStatus": { "type": "string", "description": "Status of a resource in the session resource registry.", "enum": [ "active", "completed", "failed", "released" ] }, "SessionSandboxAction": { "type": "string", "description": "Operator action to take against a session's managed sandbox. `Pause`\nsuspends the instance, `Resume` restarts it, `Delete` releases the\nlease.", "enum": [ "pause", "resume", "delete" ] }, "SessionSandboxStatusValue": { "type": "string", "description": "Wire-facing status of a session sandbox. Mirrors\n`everruns_platform::session_sandbox::SessionSandboxStatus` for the public API.", "enum": [ "running", "paused", "lost" ] }, "SessionSource": { "type": "string", "description": "How a session came into existence.\n\nClosed set: the sessions facet rail enumerates every variant, so the value\nis typed rather than a free-form string. Ingress paths set it server-side —\nclients may only declare the two variants they can legitimately be\n(`Chat` and `Api`), which keeps a facet like \"started by a schedule\"\ntrustworthy. Rows that predate the column, or whose origin could not be\ninferred at backfill time, carry `Unknown`.", "enum": [ "chat", "api", "slack", "ag_ui", "fcp", "schedule", "webhook", "a2a", "eval", "subagent", "unknown" ] }, "SessionStartedData": { "type": "object", "description": "Data for session.started event", "required": [ "harness_id" ], "properties": { "agent_id": { "type": [ "string", "null" ], "description": "Agent ID (optional)", "example": "agent_01933b5a00007000800000000000001" }, "harness_id": { "type": "string", "description": "Harness ID", "example": "harness_01933b5a00007000800000000000001" }, "model_id": { "type": [ "string", "null" ], "description": "Model ID if specified", "example": "model_01933b5a00007000800000000000001" } } }, "SessionStatsResponse": { "type": "object", "description": "Response for session statistics endpoint", "required": [ "total", "active", "idle", "started", "waiting_for_tool_results" ], "properties": { "active": { "type": "integer", "format": "int32", "description": "Sessions with a turn currently running", "minimum": 0 }, "idle": { "type": "integer", "format": "int32", "description": "Sessions waiting for next input", "minimum": 0 }, "started": { "type": "integer", "format": "int32", "description": "Sessions just created, no turn executed yet", "minimum": 0 }, "total": { "type": "integer", "format": "int32", "description": "Total number of sessions across all statuses", "minimum": 0 }, "waiting_for_tool_results": { "type": "integer", "format": "int32", "description": "Sessions waiting for client-side tool results", "minimum": 0 } } }, "SessionStatus": { "type": "object", "required": [ "session_id", "status", "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/AgentMessage" } }, "session_id": { "type": "string" }, "status": { "type": "string" } } }, "SessionTask": { "type": "object", "description": "A unit of background work owned by a session.", "required": [ "id", "session_id", "kind", "display_name", "state", "created_at", "updated_at" ], "properties": { "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/TaskArtifact" } }, "attempt": { "type": "integer", "format": "int32", "description": "Execution attempt, starting at 1. Incremented on re-attach." }, "cancel_requested_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Cooperative cancel intent. A flag, not a state." }, "created_at": { "type": "string", "format": "date-time" }, "display_name": { "type": "string", "description": "Human-readable label." }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaskError" } ] }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "heartbeat_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "description": "`task_*` public ID." }, "input_request": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaskInputRequest", "description": "Pending ask while `awaiting_input`; cleared when answered." } ] }, "kind": { "type": "string", "description": "Task kind: \"subagent\", \"external_agent\", \"background_tool\", \"monitor\", …" }, "links": { "$ref": "#/components/schemas/TaskLinks" }, "progress": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BackgroundProgress" } ] }, "result_path": { "type": [ "string", "null" ], "description": "Machine result in the session VFS: `/.tasks/{task_id}/result.json`." }, "root_session_id": { "type": [ "string", "null" ], "description": "Root of the owning session's delegation tree (EVE-680). Populated on\nAPI reads from the denormalized storage column so cross-session tooling\n(e.g. the Work view) can group a whole tree's tasks by one id. `None`\nfor a top-level session that is its own root, or when unavailable.\nStorage-derived, never client-settable on create." }, "session_id": { "type": "string", "description": "Owning session." }, "spec": { "type": "object", "description": "Kind-specific input (instructions, tool args, external agent id)." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "$ref": "#/components/schemas/SessionTaskState" }, "state_detail": { "type": [ "string", "null" ], "description": "Short live status line (\"polling remote task\", \"iteration 4/10\")." }, "summary": { "type": [ "string", "null" ], "description": "Human-readable outcome." }, "updated_at": { "type": "string", "format": "date-time" }, "wake_policy": { "$ref": "#/components/schemas/TaskWakePolicy" }, "worker_id": { "type": [ "string", "null" ] } } }, "SessionTaskDetail": { "type": "object", "description": "Task snapshot plus the recent message thread.", "required": [ "task", "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/TaskMessage" } }, "task": { "$ref": "#/components/schemas/SessionTask" } } }, "SessionTaskEventData": { "type": "object", "description": "Data for task lifecycle events (`task.created`, `task.updated`).\n\nCarries the full task snapshot so consumers never need a follow-up read;\nUIs reconcile by `task.id` (snapshot-then-delta).", "required": [ "task" ], "properties": { "task": { "$ref": "#/components/schemas/SessionTask" } } }, "SessionTaskState": { "type": "string", "description": "Lifecycle state of a session task.\n\nThree classes: active (`queued`, `running`), interrupted (`awaiting_input`,\nresumable), terminal (`succeeded`, `failed`, `canceled`). Timeout and\nrejection are `error.kind` values on `failed`, not states.", "enum": [ "queued", "running", "awaiting_input", "succeeded", "failed", "canceled" ] }, "SessionTitleUpdatedData": { "type": "object", "description": "Data for `session.title.updated`.", "required": [ "title" ], "properties": { "previous_title": { "type": [ "string", "null" ], "description": "Title before the mutation. `None` means the session was untitled." }, "title": { "type": "string", "description": "New session title." } } }, "SetAgentCredentialValueRequest": { "type": "object", "description": "Request to replace a credential binding's encrypted value.", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "Write-only credential value. It is encrypted and never returned.", "example": "vsk_disposable_example" } } }, "SetDefaultAgentVersionRequest": { "type": "object", "description": "Request body for the `set_default_agent_version` operation.", "required": [ "version_id" ], "properties": { "version_id": { "type": "string", "description": "Agent version's prefixed public identifier.", "example": "agentver_01933b5a00007000800000000000001" } } }, "SideEffectClass": { "type": "string", "description": "How many times a tool call may safely be executed given the same inputs.\n\nUsed by the durable Act activity (EVE-530) to decide what to do when a\nprior execution attempt left a `running` claim in `durable_tool_results`:\n\n* `Pure` / `Idempotent` — the running claim is stale; re-execute freely.\n* `AtMostOnce` — never re-execute from a stale running claim; settle it\n as `interrupted` and surface an uncertain result to the model instead.\n\nWhen unset (`None`), the conservative default is `AtMostOnce`.", "enum": [ "Pure", "Idempotent", "AtMostOnce" ] }, "Skill": { "type": "object", "description": "Skill entity (API response type)", "required": [ "id", "name", "description", "source_type", "status", "version", "created_at", "updated_at" ], "properties": { "allowed_tools": { "type": [ "string", "null" ], "description": "Comma-separated list of tool patterns this skill may invoke. `None` means inherit from the harness." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this skill was archived, if any (RFC 3339). Archived skills are hidden from default list views." }, "compatibility": { "type": [ "string", "null" ], "description": "Compatibility marker describing host-runtime requirements declared by the skill (e.g. min platform version). Informational." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this skill was created (RFC 3339)." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this skill was hard-deleted, if any (RFC 3339)." }, "description": { "type": "string", "description": "Short, agent- and user-readable summary of what the skill does and when to use it.", "example": "Extract text and tables from PDF files." }, "disable_model_invocation": { "type": "boolean", "description": "When `true`, the LLM is prevented from auto-invoking this skill; only the user can trigger it explicitly." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "skill_01933b5a00007000800000000000001" }, "license": { "type": [ "string", "null" ], "description": "License string as declared by the skill author (e.g. `MIT`, `Apache-2.0`). Informational; not enforced." }, "metadata": { "type": "object", "description": "Free-form metadata declared by the skill author.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Stable kebab-case slug used to invoke the skill (e.g. `/pdf-processing` in chat). Safe to render in user-facing messages.", "example": "pdf-processing" }, "source_type": { "$ref": "#/components/schemas/SkillSourceType", "description": "How the skill content is sourced (filesystem, URL, embedded). Determines reload semantics." }, "status": { "$ref": "#/components/schemas/SkillStatus", "description": "Current lifecycle status (`active`, `archived`, `deleted`)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this skill was last updated (RFC 3339)." }, "user_invocable": { "type": "boolean", "description": "Whether this skill appears as a `/`-prefixed slash command for end users in chat UIs." }, "version": { "type": "string", "description": "Semver string declared by the skill author. Free-form; sorted lexicographically when comparing." } } }, "SkillContent": { "type": "object", "description": "Skill content response (for /content endpoint)", "required": [ "skill_md", "files" ], "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/SkillFileEntry" } }, "skill_md": { "type": "string" } } }, "SkillFileEntry": { "type": "object", "description": "A file entry in a skill archive", "required": [ "path", "content" ], "properties": { "content": { "type": "string" }, "path": { "type": "string" } } }, "SkillSourceType": { "type": "string", "description": "Skill source type", "enum": [ "markdown", "archive" ] }, "SkillStatus": { "type": "string", "description": "Skill lifecycle status", "enum": [ "active", "disabled", "archived", "deleted" ] }, "SkillUsage": { "type": "object", "description": "Number of agents and harnesses that reference a skill via its\n`skill:{uuid}` capability id. The `/v1/skills/usage` endpoint returns this\nkeyed by public `SkillId`; skills with no references are omitted from the\nmap and the UI defaults missing entries to zero.", "required": [ "agents", "harnesses" ], "properties": { "agents": { "type": "integer", "format": "int64", "minimum": 0 }, "harnesses": { "type": "integer", "format": "int64", "minimum": 0 } } }, "SkillValidationResult": { "type": "object", "description": "Validation result for SKILL.md", "required": [ "valid" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Parsed skill description. `None` when not present in the input or unparseable." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Hard validation errors. Non-empty if and only if `valid` is `false`." }, "name": { "type": [ "string", "null" ], "description": "Parsed skill slug from the front matter. `None` when the input could not be parsed enough to extract a name." }, "valid": { "type": "boolean", "description": "`true` when the candidate SKILL.md parsed and passes all hard checks; `false` if any error was found." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal warnings (style, deprecated patterns, optional fields missing). Emitted alongside a `valid` result." } } }, "Speed": { "type": "string", "description": "Speed level for models that expose a latency/price service tier.\nWire values map 1:1 to the OpenAI `service_tier` request parameter:\n`flex` (slower, cheaper), `default` (standard), `priority` (faster,\npremium). `auto` is deliberately not offered — omitting the field\npreserves the provider's default routing.", "enum": [ "flex", "default", "priority" ] }, "SpeedConfig": { "type": "object", "description": "Speed configuration for a model", "required": [ "values", "default" ], "properties": { "default": { "$ref": "#/components/schemas/Speed", "description": "Default speed for this model" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/SpeedValue" }, "description": "Available speed values for this model" } } }, "SpeedValue": { "type": "object", "description": "Named speed value for UI display", "required": [ "value", "name" ], "properties": { "name": { "type": "string", "description": "Display name (e.g., \"Flex\", \"Fast\")" }, "value": { "$ref": "#/components/schemas/Speed", "description": "The API value (e.g., \"flex\", \"priority\")" } } }, "StatRequest": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } }, "SubmitToolResultsRequest": { "type": "object", "description": "Request to submit client-side tool results", "required": [ "tool_results" ], "properties": { "tool_results": { "type": "array", "items": { "$ref": "#/components/schemas/ClientToolResult" }, "description": "Tool results from the client", "example": [ { "result": { "url": "https://example.com/orders/42" }, "tool_call_id": "toolu_01933b5a00007000800000000000001" } ] } } }, "SubmitToolResultsResponse": { "type": "object", "description": "Response from submitting tool results", "required": [ "accepted", "status" ], "properties": { "accepted": { "type": "integer", "description": "Number of tool results accepted", "minimum": 0 }, "status": { "type": "string", "description": "Session status after submission" } } }, "SubmittedAnswer": { "type": "object", "description": "One submitted answer.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Question id, as carried in the `tool.call_requested` payload." }, "other_text": { "type": [ "string", "null" ], "description": "Free text, accepted only when the question allows it." }, "secret_ref": { "type": [ "string", "null" ], "description": "Handle to the stored credential, on a `secret` question only — the value\nitself is never submitted here. Store it with\n`PUT /v1/sessions/{session_id}/storage/secrets` first, then answer with\n`session:{secret_name}`.", "example": "session:STRIPE_API_KEY" }, "selected": { "type": "array", "items": { "type": "string" }, "description": "Chosen option labels. Must be labels that were actually offered." } } }, "SubmittedStatus": { "type": "string", "description": "The outcomes a caller may submit.\n\n`cancelled` and `timed_out` are deliberately absent: they are the server's to\ndecide, from a superseding message and from the deadline sweep. A caller that\ncould assert them could claim a person's silence as their answer.", "enum": [ "answered", "declined" ] }, "SuccessResponse": { "type": "object", "description": "Generic success response", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "SwitchOrgRequest": { "type": "object", "description": "Request to switch organization", "required": [ "org_id" ], "properties": { "org_id": { "type": "string", "description": "Organization public ID to switch to", "example": "org_2f3c1b3e6a9d4c6f8a1d4e9c9b7f21a0" } } }, "SwitchOrgResponse": { "type": "object", "description": "Response from switch org endpoint", "required": [ "success", "org_id" ], "properties": { "org_id": { "type": "string", "description": "The organization ID that was switched to" }, "success": { "type": "boolean", "description": "Whether the switch was successful" } } }, "SyncModelsResponse": { "oneOf": [ { "type": "object", "description": "Sync completed successfully", "required": [ "created", "updated", "stale", "status" ], "properties": { "created": { "type": "integer", "description": "Number of new models discovered", "minimum": 0 }, "stale": { "type": "integer", "description": "Number of models marked as stale (not seen in this sync)", "minimum": 0 }, "status": { "type": "string", "enum": [ "success" ] }, "updated": { "type": "integer", "description": "Number of existing models updated", "minimum": 0 } } }, { "type": "object", "description": "Provider doesn't support model discovery", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "not_supported" ] } } } ], "description": "Response from syncing models from a provider" }, "TaskArtifact": { "type": "object", "description": "Typed link to something the task produced.", "required": [ "name", "type" ], "properties": { "name": { "type": "string" }, "path": { "type": [ "string", "null" ], "description": "Session VFS path, when the artifact lives in the session filesystem." }, "type": { "type": "string", "description": "Artifact type: \"file\", \"url\", \"session\", \"pr\", etc." }, "url": { "type": [ "string", "null" ], "description": "External URL, when the artifact lives elsewhere." } } }, "TaskError": { "type": "object", "description": "Terminal error detail. Timeout/rejection/orphaned are kinds, not states.", "required": [ "kind", "message" ], "properties": { "kind": { "type": "string" }, "message": { "type": "string" } } }, "TaskInputRequest": { "type": "object", "description": "Structured ask posted by a task that needs input to continue.", "required": [ "id", "prompt" ], "properties": { "expected": { "type": "object", "description": "Optional machine-readable description of the expected answer." }, "id": { "type": "string", "description": "Stable ID referenced by the answering message's `in_reply_to`." }, "prompt": { "type": "string", "description": "Human/agent-readable prompt." } } }, "TaskLinks": { "type": "object", "description": "Cross-references owned by a task.", "properties": { "child_session_id": { "type": [ "string", "null" ], "description": "Child session, for subagent-shaped tasks. Full transcript lives there." }, "remote_task_id": { "type": [ "string", "null" ], "description": "Remote task ID, for tasks wrapping an external protocol task (A2A)." }, "resource_ids": { "type": "array", "items": { "type": "string" }, "description": "Session resources (sandboxes, browser sessions) this task holds." } } }, "TaskMessage": { "type": "object", "description": "A message exchanged between a session and one of its tasks.", "required": [ "id", "task_id", "direction", "content", "created_at" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TaskMessagePart" } }, "created_at": { "type": "string", "format": "date-time" }, "direction": { "$ref": "#/components/schemas/TaskMessageDirection" }, "id": { "type": "string", "description": "`tmsg_*` public ID." }, "in_reply_to": { "type": [ "string", "null" ], "description": "Set when this message answers a `TaskInputRequest`." }, "task_id": { "type": "string" } } }, "TaskMessageDirection": { "type": "string", "description": "Direction of a task message. Inbound = session → task.", "enum": [ "inbound", "outbound" ] }, "TaskMessageEventData": { "type": "object", "description": "Data for task message events (`task.message.sent`, `task.message.received`).", "required": [ "task_id", "message" ], "properties": { "message": { "$ref": "#/components/schemas/TaskMessage" }, "task_id": { "type": "string" } } }, "TaskMessagePart": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "type": "object" }, "type": { "type": "string", "enum": [ "data" ] } } } ], "description": "One content part of a task message." }, "TaskPushConfig": { "type": "object", "description": "Public view of a per-task push config. The stored secret is NEVER returned —\nonly `has_secret` signals whether one is configured.", "required": [ "id", "url", "has_secret", "event_filter", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When the config was created (RFC 3339).", "example": "2026-07-11T00:00:00Z" }, "event_filter": { "type": "array", "items": { "type": "string" }, "description": "Events that trigger delivery (terminal, awaiting_input, message)." }, "has_secret": { "type": "boolean", "description": "Whether a signing secret is configured (the secret itself is never returned).", "example": true }, "id": { "type": "string", "description": "Public identifier (tpc_<32-hex-chars>).", "example": "tpc_9f8c2b1a4e7d4c3b8a1f2e3d4c5b6a7f" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the config was last updated (RFC 3339).", "example": "2026-07-11T00:00:00Z" }, "url": { "type": "string", "description": "Target URL that receives POST deliveries.", "example": "https://hooks.example.com/everruns/tasks" } } }, "TaskResponse": { "type": "object", "description": "Task response", "required": [ "id", "activity_id", "activity_type", "status", "priority", "attempt", "max_attempts", "created_at" ], "properties": { "activity_id": { "type": "string", "description": "Stable per-workflow activity ID (used for deduplication within a workflow run).", "example": "tool_call_0042" }, "activity_type": { "type": "string", "description": "Activity type name, used by workers to route the task.", "example": "tool_call" }, "attempt": { "type": "integer", "format": "int32", "description": "Attempt counter. `0` before the task has ever been claimed; incremented to `1` on the first claim and once more per retry.", "example": 1, "minimum": 0 }, "claimed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this task was last claimed by a worker (RFC 3339). `None` if never claimed.", "example": "2026-05-27T15:24:03Z" }, "claimed_by": { "type": [ "string", "null" ], "description": "Worker ID that holds the current claim; `None` if pending or terminal.", "example": "worker-7f3a9b2e-1c4d-4a5f-8b6c-9d0e1f2a3b4c" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this task was enqueued (RFC 3339).", "example": "2026-05-27T15:24:00Z" }, "id": { "type": "string", "format": "uuid", "description": "UUID of the task.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "last_error": { "type": [ "string", "null" ], "description": "Last error message recorded by the worker; `None` if the task has never failed.", "example": "tool exceeded 30s budget" }, "max_attempts": { "type": "integer", "format": "int32", "description": "Maximum number of attempts before the task is sent to the DLQ.", "example": 5, "minimum": 0 }, "priority": { "type": "integer", "format": "int32", "description": "Priority; higher values run first within the same activity type.", "example": 10 }, "status": { "type": "string", "description": "Current lifecycle status (`pending`, `claimed`, `completed`, `failed`, `dead`, `cancelled`).", "example": "claimed" }, "workflow_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Owning workflow's identifier. `None` for one-off tasks not tied to a workflow.", "example": "9a1b2c3d-4e5f-6789-abcd-ef0123456789" } } }, "TaskWakePolicy": { "type": "string", "description": "When outbound task activity wakes the owning session's agent.", "enum": [ "silent", "on_terminal", "on_activity" ] }, "TaskWebhookResponse": { "type": "object", "description": "A configured outbound webhook target.", "required": [ "id", "url", "enabled", "has_secret", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean", "description": "Whether this webhook is enabled." }, "has_secret": { "type": "boolean", "description": "Whether a signing secret is configured (the secret itself is never returned)." }, "id": { "type": "string", "description": "Public identifier (wh_<32-hex-chars>)." }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "description": "Target URL that receives POST requests." } } }, "TasksListResponse": { "type": "object", "description": "Tasks list response", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskResponse" }, "description": "Page of items returned by this query." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages.", "minimum": 0 } } }, "TextAnnotation": { "type": "object", "description": "A claim-level citation attached to a span of generated text.\n\nThe single shared type across every citation capability: a text span linked\nto a source. Producers agree only on this render contract — each capability\nkeeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps\ninto this envelope at emit time. See `knowledge/runtime-resources/citations.md`.", "required": [ "start", "end", "origin", "source" ], "properties": { "end": { "type": "integer", "description": "Exclusive end char offset.", "example": 19, "minimum": 0 }, "external_id": { "type": [ "string", "null" ], "description": "Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted\nby the render contract.", "example": "kchk_01j9y3q8w2" }, "origin": { "type": "string", "description": "Capability id that produced this annotation (e.g. `citation_retrieval`).\nLets the UI and evals attribute and filter each citation by feed.", "example": "citation_retrieval" }, "source": { "$ref": "#/components/schemas/AnnotationSource", "description": "The cited source." }, "start": { "type": "integer", "description": "0-indexed start char offset into the enclosing `TextContentPart.text`.", "example": 0, "minimum": 0 }, "verified": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VerificationVerdict", "description": "Verification verdict, filled by the `citation_verification` capability.\nAbsent means unverified (not \"unsupported\")." } ] } } }, "TextContentPart": { "type": "object", "description": "Text content part", "required": [ "text" ], "properties": { "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/TextAnnotation" }, "description": "Claim-level citations attached to spans of `text`.\n\nThe narrow render contract shared by all citation capabilities (see\n`knowledge/runtime-resources/citations.md`). Empty for non-cited text, so the wire shape of\nexisting messages is unchanged." }, "text": { "type": "string" } } }, "TokenUsage": { "type": "object", "description": "Token usage statistics\n\nTracks token consumption per LLM call including cache tokens for cost\noptimization.\n\n# Disjoint bucket convention\n\nPrompt token buckets are **disjoint** (non-overlapping). Drivers normalize\nprovider wire formats at the boundary so this holds for every provider:\n\n```text\ntotal_prompt = input_tokens + cache_read_tokens + cache_creation_tokens\n```\n\n- `input_tokens` — non-cached prompt tokens only.\n- `cache_read_tokens` — tokens served from cache, never counted in\n `input_tokens`.\n- `cache_creation_tokens` — tokens written to cache, never counted in\n `input_tokens`.\n\nInclusive providers (OpenAI Responses / Chat Completions, Gemini) report a\nprompt count that *includes* cached reads; their drivers subtract the cached\nsubset so the value stored here is the non-cached remainder. Anthropic /\nBedrock already report disjoint buckets. Cost is therefore uniform across\nproviders (`input·in + cache_read·cr + cache_creation·cw + output·out`);\nconsumers must not re-derive a non-cached input by subtracting cache reads.", "required": [ "input_tokens", "output_tokens" ], "properties": { "actual_cost_usd": { "type": [ "number", "null" ], "format": "double", "description": "Actual cost of this generation in USD, as reported by the provider inline\n(e.g. OpenRouter's `usage.cost`, which reflects real post-routing/BYOK/cache\npricing). `None` for providers that do not return a cost." }, "cache_creation_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of tokens written to cache, disjoint from `input_tokens`", "minimum": 0 }, "cache_read_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of tokens read from cache (reduces cost), disjoint from `input_tokens`", "minimum": 0 }, "effective_cost_usd": { "type": [ "number", "null" ], "format": "double", "description": "Best-effort USD cost when it cannot be derived from actual/estimated\nalone: already-aggregated usage, or a generation carrying a cost that\nbelongs to neither slot. Per-generation usage normally leaves this unset\nand derives the effective cost from actual-else-estimated; the exception\nis a turn whose compaction cost is folded in, where the combined total\nhas to live here precisely so the generation's own actual-vs-estimated\ndistinction survives (EVE-895)." }, "estimated_cost_usd": { "type": [ "number", "null" ], "format": "double", "description": "Estimated cost of this generation in USD, derived from the model's static\nprice-table profile. Computed whenever a profile with cost data exists,\nindependently of `actual_cost_usd`, so estimate-vs-actual drift can be\nreconciled. `None` when there is no profile cost data for the model." }, "input_tokens": { "type": "integer", "format": "int32", "description": "Number of non-cached prompt tokens (cached reads/writes are tracked\nseparately; see the disjoint bucket convention on the struct)", "minimum": 0 }, "output_tokens": { "type": "integer", "format": "int32", "description": "Number of output/completion tokens", "minimum": 0 } } }, "ToolCall": { "type": "object", "description": "Tool call from LLM response", "required": [ "id", "name", "arguments" ], "properties": { "arguments": { "type": "object", "description": "Arguments as JSON" }, "id": { "type": "string", "description": "Unique ID for this tool call" }, "name": { "type": "string", "description": "Tool name to execute" } } }, "ToolCallContentPart": { "type": "object", "description": "Tool call content part (assistant requesting tool execution)", "required": [ "id", "name", "arguments" ], "properties": { "arguments": {}, "id": { "type": "string" }, "name": { "type": "string" }, "native": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NativeToolCall", "description": "Original native call, including raw custom input and async metadata." } ] } } }, "ToolCallRepairedData": { "type": "object", "description": "Data for the `tool.call_repaired` event (EVE-600).\n\nEmitted once per malformed tool call handled by the opt-in\n`tool_call_repair` capability. `outcome` is the stable label\n(`local-salvage` | `re-prompt` | `gave-up`).", "required": [ "turn_id", "tool_call_id", "tool_name", "outcome" ], "properties": { "outcome": { "type": "string", "description": "Stable outcome label: `local-salvage`, `re-prompt`, or `gave-up`." }, "tool_call_id": { "type": "string", "description": "The tool call ID that was inspected/repaired." }, "tool_name": { "type": "string", "description": "The tool name the malformed call targeted." }, "turn_id": { "type": "string", "description": "Turn this repair belongs to.", "example": "turn_01933b5a00007000800000000000001" } } }, "ToolCallRequestedData": { "type": "object", "description": "Data for tool.call_requested event\n\nEmitted when the agent needs client-side tool calls executed.\nThe workflow pauses until the client submits results via the API.", "required": [ "tool_calls" ], "properties": { "completed_headline": { "type": [ "string", "null" ], "description": "Human-readable headline after the requested batch completes" }, "headline": { "type": [ "string", "null" ], "description": "Human-readable headline for the requested batch" }, "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" }, "description": "Tool calls that need to be executed by the client" }, "tool_summaries": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCallSummary" }, "description": "Optional summaries with display names and narration for UI rendering" } } }, "ToolCallSummary": { "type": "object", "description": "Summary of a tool call (compact form without arguments)", "required": [ "id", "name" ], "properties": { "completed_narration": { "type": [ "string", "null" ], "description": "Human-readable narration after the call completes" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name for UI rendering" }, "id": { "type": "string" }, "name": { "type": "string" }, "narration": { "type": [ "string", "null" ], "description": "Human-readable narration for timeline rendering" } } }, "ToolCompletedData": { "type": "object", "description": "Data for tool.completed event", "required": [ "tool_call_id", "tool_name", "success", "status" ], "properties": { "capability_id": { "type": [ "string", "null" ], "description": "Capability that contributed the tool definition, when known." }, "capability_name": { "type": [ "string", "null" ], "description": "Human-readable capability name snapshot, when known." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name for UI rendering" }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Duration of the tool call in milliseconds", "minimum": 0 }, "error": { "type": [ "string", "null" ], "description": "Error message if failed" }, "narration": { "type": [ "string", "null" ], "description": "Human-readable narration for timeline rendering" }, "result": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ContentPart" }, "description": "Result content (for successful calls)" }, "status": { "type": "string", "description": "Status: \"success\", \"error\", \"timeout\", \"cancelled\"" }, "success": { "type": "boolean", "description": "Whether the tool call succeeded" }, "tool_call_fingerprint": { "type": [ "string", "null" ], "description": "Stable fingerprint of tool name + normalized arguments." }, "tool_call_id": { "type": "string", "description": "Tool call ID" }, "tool_name": { "type": "string", "description": "Tool name" }, "tool_result_fingerprint": { "type": [ "string", "null" ], "description": "Stable fingerprint of tool name + normalized result/error." } } }, "ToolDefinition": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/BuiltinTool", "description": "Built-in tool - executed by the worker via ToolRegistry" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "builtin" ] } } } ], "description": "Built-in tool - executed by the worker via ToolRegistry" }, { "allOf": [ { "$ref": "#/components/schemas/ClientSideTool", "description": "Client-side tool - executed by the client, not the server" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "client_side" ] } } } ], "description": "Client-side tool - executed by the client, not the server" } ], "description": "Tool definition in agent configuration" }, "ToolDefinitionSummary": { "type": "object", "description": "Summary of a tool definition (compact form for events)", "required": [ "name", "description" ], "properties": { "capability_id": { "type": [ "string", "null" ], "description": "Capability that contributed the tool definition, when known." }, "capability_name": { "type": [ "string", "null" ], "description": "Human-readable capability name snapshot, when known." }, "category": { "type": [ "string", "null" ], "description": "Tool category for namespace grouping." }, "description": { "type": "string", "description": "Tool description" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name for UI rendering" }, "name": { "type": "string", "description": "Tool name" } } }, "ToolHints": { "type": "object", "description": "Semantic hints describing a tool's behavioral properties.\n\nFollows the MCP tool annotations convention (readOnlyHint, destructiveHint,\nidempotentHint, openWorldHint) plus everruns-specific hints. All fields are\noptional booleans — `None` means \"unknown/unspecified\". Consumers should\ntreat `None` as the conservative default (e.g., assume not readonly, assume\nnot idempotent).\n\nThese hints are informational — they do not enforce policy. Use `ToolPolicy`\nfor execution gating (auto vs requires_approval).", "properties": { "capability_id": { "type": [ "string", "null" ], "description": "Capability that contributed this tool definition.\n\nReporting uses this attribution only as metadata. It must never contain\ntool arguments, results, prompts, or any other sensitive payload." }, "capability_name": { "type": [ "string", "null" ], "description": "Human-readable capability name snapshot for reporting." }, "concurrency_class": { "type": [ "string", "null" ], "description": "Scheduling conflict key. Tool calls within the same act batch that share\na non-empty `concurrency_class` are executed sequentially in arrival\norder; calls in different classes (or with no class) run concurrently.\n\nSet this on tools that mutate shared session state so that, e.g., two\nfile writes or two SQL mutations in one batch do not race. Read-only\ntools should leave this `None` so they always parallelize. See\n`everruns-engine`'s tool scheduler for how the act phase consumes it." }, "cpu_bound": { "type": [ "boolean", "null" ], "description": "Tool performs significant CPU-bound or otherwise non-yielding work in\nprocess (e.g. an in-process interpreter). When true, the act scheduler\nruns the call on its own task (`tokio::spawn`) so a long CPU burst does\nnot starve the cooperative polling of I/O-bound tools in the same batch.\n\nDistinct from `long_running`, which describes wall-clock time for\nI/O-bound work (those tools yield at await points and need no offload)." }, "destructive": { "type": [ "boolean", "null" ], "description": "Tool may irreversibly destroy or delete data.\nSubset of non-readonly — a tool can be non-readonly (writes) without\nbeing destructive (e.g., create/update operations)." }, "idempotent": { "type": [ "boolean", "null" ], "description": "Calling the tool repeatedly with the same arguments produces the same\neffect. Safe to retry on transient failures." }, "long_running": { "type": [ "boolean", "null" ], "description": "Tool may take significant time to complete (> ~5s typical).\nUseful for clients to show progress indicators and set timeouts." }, "metadata": { "description": "Host-owned annotations that core does not interpret.\n\nThe typed hints above are the vocabulary core itself reasons about. This\nis the escape hatch for everything a *host* wants to carry alongside a\ntool — risk tiers for an approval UI, presentation hints, an embedder's\nrouting keys — without adding a field to core for each one. Core reads\nnothing here and no driver sends it to a provider; it travels with the\ndefinition so a consumer sees it at the point of decision (e.g. a\n`PreToolUseHook` gating on what the tool declared).\n\nThe schema belongs to whoever writes it. Never put credentials or other\nsensitive payload here: like the rest of the definition, it is persisted\nand surfaced to clients." }, "narration_noun": { "type": [ "string", "null" ], "description": "Entity noun for operation-based narration (e.g. \"agent\", \"harness\").\nWhen set, the narration system reads the `operation` argument and\nproduces verb-based narration like \"Created agent: Neon Cartographer\"\ninstead of the generic \"Ran Manage Agents\"." }, "open_world": { "type": [ "boolean", "null" ], "description": "Tool interacts with external entities beyond the local system\n(network calls, third-party APIs, cloud services)." }, "persist_output": { "type": [ "boolean", "null" ], "description": "Tool output should be persisted to session VFS before truncation.\nWhen set, the `tool_output_persistence` capability (EVE-222, EVE-245) writes\nstdout to `/outputs/{tool_call_id}.stdout` and stderr to\n`/outputs/{tool_call_id}.stderr`, injecting `full_output`, `total_lines`,\nand `output_files` into the result." }, "readonly": { "type": [ "boolean", "null" ], "description": "Tool does not modify any state (read-only queries, lookups).\nWhen true: safe to call speculatively, result can be cached." }, "requires_secrets": { "type": [ "boolean", "null" ], "description": "Tool requires API keys, credentials, or other secrets to function.\nUseful for UI to show connection prompts and for LLMs to anticipate\nauthentication failures." }, "side_effect_class": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SideEffectClass", "description": "Replay-safety class used by the durable Act activity (EVE-530).\n\nControls what happens when a worker reclaims a stale `running` claim:\n`Pure`/`Idempotent` tools are re-executed; `AtMostOnce` tools are\nsettled as `interrupted` to prevent double side-effects.\n\n`None` is treated conservatively as `AtMostOnce`." } ] }, "supports_background": { "type": [ "boolean", "null" ], "description": "Tool supports detached background execution via `spawn_background`.\nWhen true, the tool may be executed asynchronously outside the current\nforeground tool call and report status back later." } } }, "ToolOutputDeltaData": { "type": "object", "description": "Data for tool.output.delta event.\n\nEmitted by tools during execution to stream incremental output chunks.\nThis enables live output rendering (e.g., bash stdout/stderr, command output)\nbetween tool.started and tool.completed. Generic — usable by any tool that\nproduces streamed output (bashkit, Daytona exec, subagent speech, etc.).\n\nThe consumer accumulates deltas by tool_call_id for display. The final\ntool.completed result is authoritative — deltas are informational only.", "required": [ "tool_call_id", "tool_name", "delta", "stream" ], "properties": { "delta": { "type": "string", "description": "Incremental output chunk" }, "stream": { "type": "string", "description": "Output stream identifier (e.g., \"stdout\", \"stderr\")" }, "tool_call_id": { "type": "string", "description": "Tool call ID this output belongs to" }, "tool_name": { "type": "string", "description": "Tool name" } } }, "ToolPolicy": { "type": "string", "description": "Tool policy determines how tool calls are handled", "enum": [ "auto", "requires_approval", "client_side" ] }, "ToolProgressData": { "type": "object", "description": "Data for tool.progress event.\n\nEmitted by tools during execution to report interim status updates.\nThis allows long-running tools (e.g., browser operations, sandbox setup)\nto stream progress feedback between tool.started and tool.completed.", "required": [ "tool_call_id", "tool_name", "message" ], "properties": { "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name for UI rendering" }, "message": { "type": "string", "description": "Human-readable status message (e.g., \"Connecting to browser…\")" }, "tool_call_id": { "type": "string", "description": "Tool call ID this progress belongs to" }, "tool_name": { "type": "string", "description": "Tool name" } } }, "ToolResultContentPart": { "type": "object", "description": "Tool result content part (result of tool execution)", "required": [ "tool_call_id" ], "properties": { "error": { "type": [ "string", "null" ] }, "result": {}, "tool_call_id": { "type": "string", "description": "ID of the tool call this result corresponds to" } } }, "ToolStartedData": { "type": "object", "description": "Data for tool.started event", "required": [ "tool_call" ], "properties": { "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name for UI rendering" }, "narration": { "type": [ "string", "null" ], "description": "Human-readable narration for timeline rendering" }, "tool_call": { "$ref": "#/components/schemas/ToolCall", "description": "The tool call being executed" }, "tool_call_fingerprint": { "type": [ "string", "null" ], "description": "Stable fingerprint of tool name + normalized arguments." } } }, "TopUpRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "format": "double", "description": "Amount credited back to the budget balance." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages." } } }, "TranscriptRepairAction": { "type": "string", "description": "Action taken during transcript repair for a dangling tool call.", "enum": [ "replay", "synthesize" ] }, "TranscriptRepairedData": { "type": "object", "description": "Data for transcript.repaired event (EVE-533).\n\nEmitted once per dangling tool call when transcript repair runs before a `reason` call.\nA dangling call is an assistant `tool_call` with no matching `ToolResult` in the\nmessage history. Repair makes the transcript well-formed so the next LLM call succeeds.", "required": [ "tool_call_id", "action" ], "properties": { "action": { "$ref": "#/components/schemas/TranscriptRepairAction", "description": "Action taken: `replay` (settled result reused) or `synthesize` (interrupted placeholder added)." }, "tool_call_id": { "type": "string", "description": "The tool call ID that was repaired." }, "tool_name": { "type": [ "string", "null" ], "description": "The tool name, if known." } } }, "TriggerAgentEndpointOutput": { "type": "object", "description": "Result of running an Agent schedule endpoint immediately.", "required": [ "session_id", "created_session" ], "properties": { "created_session": { "type": "boolean", "description": "Whether the invocation created a new session." }, "session_id": { "$ref": "#/components/schemas/sessionId", "description": "Session started or reused by the invocation." } } }, "TriggerAgentTriggerOutput": { "type": "object", "required": [ "session_id", "created_session" ], "properties": { "created_session": { "type": "boolean" }, "session_id": { "$ref": "#/components/schemas/sessionId", "description": "Session's prefixed public identifier." } } }, "TriggerResponse": { "type": "object", "description": "Manual trigger response", "required": [ "execution_id" ], "properties": { "execution_id": { "type": "string", "format": "uuid", "description": "Schedule execution's identifier." } } }, "TurnCancelledData": { "type": "object", "description": "Data for turn.cancelled event", "required": [ "turn_id" ], "properties": { "reason": { "type": [ "string", "null" ], "description": "Reason for cancellation" }, "turn_id": { "type": "string", "description": "Turn identifier", "example": "turn_01933b5a00007000800000000000001" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Token usage before cancellation (if available)" } ] } } }, "TurnCompletedData": { "type": "object", "description": "Data for turn.completed event", "required": [ "turn_id", "iterations" ], "properties": { "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Duration in milliseconds", "minimum": 0 }, "final_answer_preview": { "type": [ "string", "null" ], "description": "Bounded preview of the final visible assistant answer." }, "final_message_id": { "type": [ "string", "null" ], "description": "Canonical assistant message emitted by `output.message.completed`.", "example": "message_01933b5a00007000800000000000001" }, "input_content": { "type": [ "string", "null" ], "description": "Input message content (for observability, passed through from turn.started)" }, "iterations": { "type": "integer", "format": "int32", "description": "Number of iterations in this turn", "minimum": 0 }, "llm_call_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of LLM generation calls executed during the turn.", "minimum": 0 }, "status": { "type": [ "string", "null" ], "description": "Optional explicit completion status for consumers that summarize turns." }, "time_to_first_token_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "First-token latency for the turn, usually from the first LLM generation.", "minimum": 0 }, "tool_call_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of tool calls completed during the turn.", "minimum": 0 }, "turn_id": { "type": "string", "description": "Turn identifier", "example": "turn_01933b5a00007000800000000000001" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Aggregated token usage for all LLM calls in this turn" } ] } } }, "TurnFailedData": { "type": "object", "description": "Data for turn.failed event", "required": [ "turn_id", "error" ], "properties": { "error": { "type": "string", "description": "Error message" }, "error_code": { "type": [ "string", "null" ], "description": "Error code" }, "error_disclosure": { "type": [ "string", "null" ], "description": "Error-disclosure mode applied to `error_code`/`error_fields`\n(\"generic\" | \"standard\" | \"detailed\"). Full diagnostic detail remains\navailable to operators via reason.completed failure events and tracing." }, "error_fields": { "type": [ "object", "null" ], "description": "Structured interpolation fields for localized error rendering." }, "turn_id": { "type": "string", "description": "Turn identifier", "example": "turn_01933b5a00007000800000000000001" } } }, "TurnSealedData": { "type": "object", "description": "Data for turn.sealed event (EVE-534).\n\nA sealed turn was deliberately stopped to prevent waste. It is observably\ndistinct from `turn.completed` (success) and `turn.failed` (error). The\n`reason` is the durable engine's stable seal-reason wire value.\n(`\"no_progress\"` or `\"budget\"`).", "required": [ "turn_id", "reason" ], "properties": { "detail": { "type": [ "string", "null" ], "description": "Human-readable detail for operators (optional)." }, "iterations": { "type": [ "integer", "null" ], "format": "int32", "description": "Iterations completed before the turn was sealed (if known).", "minimum": 0 }, "reason": { "type": "string", "description": "Why the turn was sealed: `\"no_progress\"` (crash-loop with no forward\nprogress) or `\"budget\"` (work budget exhausted)." }, "turn_id": { "type": "string", "description": "Turn identifier", "example": "turn_01933b5a00007000800000000000001" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Aggregated token usage before sealing, if available." } ] } } }, "TurnStartedData": { "type": "object", "description": "Data for turn.started event", "required": [ "turn_id", "input_message_id" ], "properties": { "agent_description": { "type": [ "string", "null" ], "description": "Agent description snapshot at turn start." }, "agent_id": { "type": [ "string", "null" ], "description": "Agent the turn runs as, when the session is bound to one. Carried on\nthe turn root so trace exporters can label the `invoke_agent` span\nwithout a store lookup (the Gen-AI conventions want the agent name in\nthe span name and `gen_ai.agent.*` attributes).", "example": "agent_01933b5a00007000800000000000001" }, "agent_name": { "type": [ "string", "null" ], "description": "Human-readable agent name snapshot at turn start." }, "input_content": { "type": [ "string", "null" ], "description": "Input message content (for observability)" }, "input_message_id": { "type": "string", "description": "Input message ID that triggered this turn", "example": "message_01933b5a00007000800000000000001" }, "turn_id": { "type": "string", "description": "Turn identifier", "example": "turn_01933b5a00007000800000000000001" } } }, "TurnWaitResponse": { "type": "object", "description": "Waited result for `POST /v1/sessions/{session_id}/messages?wait=true`.", "required": [ "status", "message", "messages" ], "properties": { "error": { "type": [ "string", "null" ], "description": "Turn failure detail when `status` is `failed`.", "example": "turn failed: upstream model error" }, "message": { "$ref": "#/components/schemas/Message", "description": "The accepted user message (same body as the `201` path)." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Messages appended after the accepted message: assistant output on\ncompletion, whatever exists so far on timeout, empty on failure." }, "status": { "$ref": "#/components/schemas/TurnWaitStatus", "description": "Wait outcome for the triggered turn." } } }, "TurnWaitStatus": { "type": "string", "description": "Terminal-or-pending outcome of a waited turn.", "enum": [ "completed", "failed", "timeout" ], "example": "completed" }, "UpdateAgentEndpointRequest": { "type": "object", "description": "Request to update an ingress endpoint owned by an Agent.", "properties": { "channel_config": { "description": "Replacement transport-specific endpoint configuration." }, "enabled": { "type": [ "boolean", "null" ], "description": "Whether the endpoint can accept ingress traffic." } } }, "UpdateAgentRequest": { "type": "object", "description": "Request to update an agent. Only provided fields will be updated.", "properties": { "capabilities": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities to enable for this agent with per-agent configuration.\nReplaces existing capabilities. Each has a `ref` (capability ID) and optional `config`.", "example": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "web_fetch" } ] }, "default_model_id": { "type": [ "string", "null" ], "description": "The ID of the default LLM model to use for this agent.", "example": "model_01933b5a00007000800000000000001" }, "description": { "type": [ "string", "null" ], "description": "A human-readable description of what the agent does.", "example": "Updated description for the agent" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI.", "example": "Updated Support Agent" }, "harness_id": { "type": [ "string", "null" ], "description": "Harness ID used as this agent's base execution environment. Omit to leave unchanged.", "example": "harness_01933b5a00007000800000000000001" }, "harness_name": { "type": [ "string", "null" ], "description": "Addressable harness name. Alternative to `harness_id`; omit to leave unchanged.", "example": "generic" }, "initial_files": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this agent.", "example": [ { "content": "Always respond in formal English.\n", "path": "INSTRUCTIONS.md" } ] }, "intro_markdown": { "type": [ "string", "null" ], "description": "Markdown intro for fresh Platform Chat threads. Outer `None` leaves\nunchanged; inner `None` clears.", "example": "Hey, I'm Ava. Ask me anything about your account." }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this agent.", "example": 20, "minimum": 0 }, "mcpServers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this agent." } ] }, "name": { "type": [ "string", "null" ], "description": "Name, unique per org. Lowercase alphanumeric and hyphens.", "example": "updated-support" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs this agent's sessions can reach.\nSend `{}` (empty object) to clear restrictions. Omit to leave unchanged.\nExample shape is defined on `NetworkAccessList`." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598). `true` signals\nthe provider that parallel tool calls are wanted; `false` requests at\nmost one tool call per turn and forces serial execution. Omit to leave\nunchanged.", "example": true }, "short_description": { "type": [ "string", "null" ], "description": "One-line description in simplified Markdown. Outer `None` leaves\nunchanged; inner `None` clears.", "example": "Answers account questions in seconds." }, "starters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters; omit to leave unchanged, send empty to clear.\n`icon` reuses the harness icon name set." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentStatus", "description": "The status of the agent. Set to \"archived\" to soft-delete." } ] }, "system_prompt": { "type": [ "string", "null" ], "description": "The system prompt that defines the agent's behavior and capabilities.", "example": "You are an updated helpful assistant." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tags for organizing and filtering agents.", "example": [ "updated-tag" ] }, "tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools for this agent.\nReplaces existing tools if provided.", "example": [ { "description": "Open URL in the user's browser", "name": "open_url", "parameters": { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "type": "client_side" } ] } } }, "UpdateAgentTriggerRequest": { "type": "object", "description": "Request to update a trigger. Only provided fields change; the rest are\npreserved from the stored config.", "properties": { "auth": { "description": "Shared endpoint auth is not supported by webhook triggers." }, "cron_expression": { "type": [ "string", "null" ], "description": "Replacement cron expression." }, "enabled": { "type": [ "boolean", "null" ], "description": "Replacement enabled state." }, "message": { "type": [ "string", "null" ], "description": "Replacement message sent when the trigger fires." }, "rate_limit_per_minute": { "type": [ "integer", "null" ], "format": "int32", "description": "Replacement per-ingress, per-IP webhook request limit.", "minimum": 0 }, "session_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SessionBinding", "description": "Replacement session reuse strategy." } ] }, "timezone": { "type": [ "string", "null" ], "description": "Replacement IANA timezone identifier." }, "token": { "type": [ "string", "null" ], "description": "Replacement webhook token." } } }, "UpdateBudgetRequest": { "type": "object", "description": "Request body for changing a spending budget.", "properties": { "limit": { "type": [ "number", "null" ], "format": "double", "description": "Replacement hard spending ceiling.", "example": 150.0 }, "metadata": { "description": "Free-form metadata attached to this resource." }, "soft_limit": { "type": [ "number", "null" ], "format": "double", "description": "Replacement soft threshold, or null to remove the threshold." }, "status": { "type": [ "string", "null" ], "description": "Current lifecycle status." } } }, "UpdateDeclarativeCapabilityRequest": { "type": "object", "description": "Request body for the `update_declarative_capability` operation.", "properties": { "definition": { "type": "object", "description": "Replacement declarative definition. Changing `name` updates the canonical capability ref after uniqueness validation." }, "status": { "type": [ "string", "null" ], "description": "Optional lifecycle state update. Use `disabled` to hide from runtime selection without archiving.", "example": "disabled" } } }, "UpdateFileRequest": { "type": "object", "description": "Request to update a file", "properties": { "content": { "type": [ "string", "null" ], "description": "New file content", "example": "# Project notes (rev 2)\n\nUpdated migration plan with rollback steps.\n" }, "encoding": { "type": [ "string", "null" ], "description": "Content encoding: \"text\" or \"base64\". Defaults to text.", "example": "text" }, "is_readonly": { "type": [ "boolean", "null" ], "description": "Whether file is read-only", "example": false } } }, "UpdateHarnessRequest": { "type": "object", "description": "Request to update a harness. Only provided fields will be updated.", "properties": { "capabilities": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Replace the capability list entirely; omit to leave unchanged.", "example": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "web_fetch" } ] }, "default_model_id": { "type": [ "string", "null" ], "description": "New default model selected when sessions inherit from this harness; omit to leave unchanged.", "example": "model_01933b5a00007000800000000000001" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Research harness with web tools" }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name.", "example": "Updated Research Harness" }, "embedder_metadata": { "type": [ "object", "null" ], "description": "Replace the embedder metadata map entirely; omit to leave unchanged.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "initial_files": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Replace the initial-files list entirely; omit to leave unchanged.", "example": [ { "content": "Cite sources verbatim.\n", "path": "INSTRUCTIONS.md" } ] }, "intro_markdown": { "type": [ "string", "null" ], "description": "Markdown intro shown as an intro box on a fresh Platform Chat thread.\nOuter `None` leaves unchanged; inner `None` clears.", "example": "I triage incidents, dig through logs, and draft the update." }, "mcpServers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BTreeMap", "description": "Replace the scoped MCP server set entirely; omit to leave unchanged." } ] }, "name": { "type": [ "string", "null" ], "description": "Name, unique per org.", "example": "updated-research" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list. Send `{}` (empty object) to clear. Omit to leave unchanged.\nExample shape is defined on `NetworkAccessList`." } ] }, "parent_harness_id": { "type": [ "string", "null" ], "description": "New parent harness for inheritance. Outer `None` leaves unchanged; inner `None` removes inheritance (becomes a root harness)." }, "short_description": { "type": [ "string", "null" ], "description": "One-line description in simplified Markdown. Outer `None` leaves\nunchanged; inner `None` clears.", "example": "Triage incidents, dig through logs, draft the update." }, "starters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters; omit to leave unchanged, send empty to clear.\n`icon` reuses the harness icon name set." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HarnessStatus", "description": "Current lifecycle status. Example shape is defined on `HarnessStatus`." } ] }, "system_prompt": { "type": [ "string", "null" ], "description": "New system prompt the harness contributes to sessions; omit to leave unchanged.", "example": "You are a research assistant. Cite sources verbatim." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Replace the tag list entirely; omit to leave unchanged.", "example": [ "research", "web-tools" ] } } }, "UpdateInstalledPluginRequest": { "type": "object", "description": "Request body for updating an installed plugin (status only; use POST .../update for recompile).", "properties": { "status": { "type": [ "string", "null" ], "description": "New lifecycle status: `active` or `disabled`." } } }, "UpdateKnowledgeBaseRequest": { "type": "object", "description": "Request body for the `update_knowledge_base` operation.", "properties": { "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages." }, "embedding_model_id": { "type": [ "string", "null" ], "description": "Optional embedding model for hybrid retrieval. Set to null to clear." }, "name": { "type": [ "string", "null" ], "description": "Human-readable name. Safe to render in user-facing messages.", "example": "support-runbooks-archive" } } }, "UpdateKnowledgeEntryRequest": { "type": "object", "description": "Request body for the `update_knowledge_entry` operation.", "properties": { "body": { "type": [ "string", "null" ], "description": "Updated entry body. Markdown is rendered when displayed.", "example": "Use the `/v1/payments/{id}/refund` endpoint with `reason: \"past_window\"`. Now requires VP approval." }, "kind": { "type": [ "string", "null" ], "description": "Discriminator selecting the variant of this resource. One of `note`,\n`table`, `business`, `query`, `runbook`.", "example": "runbook" }, "resource": { "type": [ "string", "null" ], "description": "Optional OKF resource URI. Set to null to clear." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Free-form tags attached to this resource.", "example": [ "billing", "refunds", "vp-approval" ] }, "title": { "type": [ "string", "null" ], "description": "Human-readable title. Safe to render in user-facing messages.", "example": "Refund a payment past 60 days" } } }, "UpdateKnowledgeIndexRequest": { "type": "object", "description": "Request body for the `update_knowledge_index` operation.", "properties": { "description": { "type": [ "string", "null" ], "description": "Human-readable description. Set to null to clear." }, "embedding_model_id": { "type": [ "string", "null" ], "description": "Embedding model used to embed chunks. Required; cannot be cleared." }, "name": { "type": [ "string", "null" ], "description": "Human-readable name. Safe to render in user-facing messages.", "example": "product-docs-v2" }, "source_config": { "description": "Non-secret source coordinates. Never include credentials." } } }, "UpdateMcpServerRequest": { "type": "object", "description": "Request to update an MCP server. Only provided fields will be updated.", "properties": { "api_key": { "type": [ "string", "null" ], "description": "API key for authentication. Set to update.", "example": "mcp-api-key-redacted-1234567890abcdef" }, "auth_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpServerAuthMode", "description": "Authentication mode." } ] }, "description": { "type": [ "string", "null" ], "description": "A human-readable description of what the MCP server provides.", "example": "Updated description" }, "headers": { "type": [ "object", "null" ], "description": "Additional HTTP headers for authentication.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": { "X-Atlassian-Cloud-Id": "00000000-0000-0000-0000-000000000000" } }, "name": { "type": [ "string", "null" ], "description": "The name of the MCP server.", "example": "updated-mcp-server" }, "protocol_mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpProtocolMode", "description": "Protocol-era policy (`auto`, `legacy`, `stable`, `rc`)." } ] }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpServerStatus", "description": "The status of the MCP server. Set to \"disabled\" to disable." } ] }, "transport_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpServerTransportType", "description": "Transport type." } ] }, "url": { "type": [ "string", "null" ], "description": "The URL of the MCP server endpoint.", "example": "https://mcp.example.com/v1/mcp" } } }, "UpdateMemoryFileRequest": { "type": "object", "properties": { "content": { "type": [ "string", "null" ] }, "encoding": { "type": [ "string", "null" ] } } }, "UpdateMemoryRequest": { "type": "object", "description": "Request body for the `update_memory` operation.", "properties": { "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages." }, "name": { "type": [ "string", "null" ], "description": "Human-readable name. Safe to render in user-facing messages.", "example": "design-docs" }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateMemorySourceRequest", "description": "Source configuration. Example shape is defined on `CreateMemorySourceRequest`." } ] } } }, "UpdateModelRequest": { "type": "object", "description": "Request to update an LLM model. Only provided fields will be updated.", "properties": { "capabilities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List of capabilities this model supports.", "example": [ "chat", "tools" ] }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name for the model.", "example": "GPT-4o Mini" }, "enabled": { "type": [ "boolean", "null" ], "description": "Whether this model should be enabled (visible in UI model pickers).", "example": true }, "is_favorite": { "type": [ "boolean", "null" ], "description": "Whether this model should be marked as a favorite for quick access.", "example": true }, "model_id": { "type": [ "string", "null" ], "description": "The model identifier used by the provider's API.", "example": "gpt-5.4-mini" }, "provider_id": { "type": [ "string", "null" ], "description": "Provider that owns this model.", "example": "provider_019df670b5af7db7a5685a4ad18a544a" } } }, "UpdateOrgFeatureFlagsRequest": { "type": "object", "required": [ "flags" ], "properties": { "flags": { "type": "object", "description": "Map of flag name -> enabled. Omitted flags are unchanged.", "additionalProperties": { "type": "boolean" }, "propertyNames": { "type": "string" } } } }, "UpdateOrganizationRequest": { "type": "object", "description": "Request to update an organization", "properties": { "base_harness_id": { "type": [ "string", "null" ], "description": "Base harness to use when a session is started without an explicit harness_id.", "example": "harness_01933b5a000070008000000000000601" }, "default_harness_id": { "type": [ "string", "null" ], "description": "Default harness to preselect in the UI for new sessions.\nMutually exclusive with `default_harness_name`.", "example": "harness_01933b5a000070008000000000000602" }, "default_harness_name": { "type": [ "string", "null" ], "description": "Alternative to `default_harness_id` — looked up by stable name within the org.\nMutually exclusive with `default_harness_id`.", "example": "generic" }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model for this organization. Must be enabled; pass null to use the platform\ndefault.", "example": "model_01933b5a00007000800000000000001" }, "default_provider_per_service": { "type": [ "object", "null" ], "description": "Org-level default provider per service (EVE-569). Maps a service kind\n(`chat`, `embeddings`, `realtime`, `images`, `rerank`) to the provider id\nused as that service's default, consulted after an explicit binding and\nbefore the single-active-provider fallback. When present it **replaces**\nthe whole map; each referenced provider must exist in the org.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "The display name of the organization.", "example": "Acme Corporation" } } }, "UpdatePaymentAccountRequest": { "type": "object", "description": "Request body for the `update_payment_account` operation.", "properties": { "label": { "type": [ "string", "null" ], "description": "New label, if changing.", "example": "Refund agent · USDC on Base (prod)" }, "metadata": { "description": "New free-form metadata. Replaces the existing metadata blob entirely when set.\nExample: `{\"team\": \"support\", \"cost_center\": \"ops-2026\"}`." }, "private_key": { "type": [ "string", "null" ], "description": "New private key material. Set to `Some(...)` to rotate; omit to leave unchanged.\nExample shown as an obvious placeholder — supply a real 32-byte hex value when rotating.", "example": "0x" }, "public_address": { "type": [ "string", "null" ], "description": "New public address. The outer `Option` indicates whether to update; the inner allows clearing the field." }, "status": { "type": [ "string", "null" ], "description": "New lifecycle status. Valid values: `active`, `disabled`.", "example": "disabled" } } }, "UpdatePaymentPolicyRequest": { "type": "object", "description": "Request body for the `update_payment_policy` operation.", "properties": { "allowed_capabilities": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "New capability allowlist. Outer `None` leaves the field unchanged.", "example": [ "weather.lookup", "shipping.quote", "currency.convert" ] }, "allowed_hosts": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "New host allowlist. Outer `None` leaves the field unchanged.", "example": [ "api.shippo.com", "api.openweathermap.org", "api.exchangerate.host" ] }, "max_amount_usd_per_day": { "type": [ "number", "null" ], "format": "double", "description": "New per-day cap (USD). **Advisory only — not yet enforced.** Outer `None` leaves the field unchanged; inner `None` clears the cap." }, "max_amount_usd_per_request": { "type": [ "number", "null" ], "format": "double", "description": "New per-request cap (USD). **Enforced** by the payment authority. Outer `None` leaves the field unchanged; inner `None` clears the cap." }, "max_amount_usd_per_turn": { "type": [ "number", "null" ], "format": "double", "description": "New per-turn cap (USD). **Advisory only — not yet enforced.** Outer `None` leaves the field unchanged; inner `None` clears the cap." }, "metadata": { "description": "New free-form metadata. Replaces the existing metadata blob entirely when set.\nExample: `{\"owner_team\": \"ops\", \"ticket\": \"OPS-1248\", \"review_due\": \"2026-09-01\"}`." }, "rail_preference": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "New rail preference order. Outer `None` leaves the field unchanged.", "example": [ "mpp_tempo", "x402_base" ] }, "require_approval_above_usd": { "type": [ "number", "null" ], "format": "double", "description": "New approval threshold (USD). **Advisory only — not yet enforced.** Outer `None` leaves the field unchanged; inner `None` disables the (future) gate." }, "status": { "type": [ "string", "null" ], "description": "New lifecycle status. Valid values: `active`, `disabled`.", "example": "disabled" } } }, "UpdatePluginMarketplaceRequest": { "type": "object", "description": "Request body for updating a plugin marketplace.", "properties": { "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "UpdateProfileRequest": { "type": "object", "description": "Request to update current user's profile", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "New display name", "example": "Jane Doe" } } }, "UpdateProviderRequest": { "type": "object", "description": "Request to update an LLM provider. Only provided fields will be updated.", "properties": { "api_key": { "type": [ "string", "null" ], "description": "API key for authenticating with the provider.\nWill be encrypted at rest if encryption is configured.\n\nSingle-field convenience for simple providers and programmatic clients.\nMulti-field drivers (Bedrock, MAI) should send `credentials` instead." }, "base_url": { "type": [ "string", "null" ], "description": "Base URL for the provider's API.", "example": "https://api.openai.com/v1" }, "credentials": { "type": [ "object", "null" ], "description": "Typed credential fields keyed by the driver's declared credential-schema\nfield names. Validated against the schema and assembled into the stored\ncredential document. Takes precedence over `api_key` when present.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "Display name for the provider.", "example": "OpenAI Development" }, "provider_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DriverId", "description": "The type of LLM provider (e.g., openai, anthropic)." } ] }, "request_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderRequestOptions", "description": "Extra headers and diagnostics options applied to every request sent to\nthis provider. Replaces the stored options wholesale; omit to leave them\nunchanged." } ] }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderStatus", "description": "The status of the provider. Set to \"inactive\" to disable." } ] }, "trace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderTraceConfig", "description": "Trace/observability link configuration override. Merged into the\nprovider's stored settings, preserving other settings keys." } ] } } }, "UpdateSavedReportRequest": { "type": "object", "description": "Request body for the `update_saved_report` operation.", "properties": { "dashboard": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SavedReportDashboardMetadata", "description": "Replace dashboard placement metadata. Omit to keep current placement;\nsend `null` to detach the report from its dashboard; send an object\nto overwrite the placement." } ] }, "description": { "type": [ "string", "null" ], "description": "Human-readable description. Safe to render in user-facing messages.", "example": "Rolling 60-day window; widened from 30d after the Q3 product launch." }, "name": { "type": [ "string", "null" ], "description": "Human-readable name. Safe to render in user-facing messages.", "example": "Weekly active agents — last 60 days" }, "query": { "$ref": "#/components/schemas/ReportQuery", "description": "Replace the saved report's query wholesale. Omit to keep the existing\nquery; send a new `ReportQuery` to swap it." } } }, "UpdateScheduleRequest": { "type": "object", "description": "Update schedule request", "properties": { "catch_up_missed": { "type": [ "boolean", "null" ], "description": "Catch up missed triggers", "example": true }, "cron_expression": { "type": [ "string", "null" ], "description": "New cron expression. Standard `min hour day-of-month month day-of-week` form.", "example": "0 8 * * 1-5" }, "description": { "type": [ "string", "null" ], "description": "New description", "example": "Fires the support-triage agent every weekday at 08:00 UTC" }, "enabled": { "type": [ "boolean", "null" ], "description": "Enable/disable", "example": true }, "max_catch_up": { "type": [ "integer", "null" ], "format": "int32", "description": "Max catch-up executions", "example": 3, "minimum": 0 }, "max_concurrent": { "type": [ "integer", "null" ], "format": "int32", "description": "Max concurrent executions", "example": 1, "minimum": 0 }, "retry_policy": { "description": "Retry policy (provider-specific JSON; see the durable engine's `RetryPolicy`).\nExample: `{\"max_attempts\": 3, \"initial_backoff_secs\": 30, \"backoff_multiplier\": 2.0}`." }, "target": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScheduleTarget", "description": "New target. Variant shape is defined on `ScheduleTarget`." } ] }, "timezone": { "type": [ "string", "null" ], "description": "New timezone (IANA name).", "example": "America/New_York" } } }, "UpdateSessionRequest": { "type": "object", "description": "Request to update a session. Only provided fields will be updated.", "properties": { "agent_identity_id": { "type": [ "string", "null" ], "description": "Optional resident agent identity used for unattended/background execution.", "example": "identity_01933b5a00007000800000000000001" }, "goal": { "type": [ "string", "null" ], "description": "Updated session objective.", "example": "Summarize the incident and list remediations" }, "locale": { "type": [ "string", "null" ], "description": "Session locale (BCP 47, e.g. `uk-UA`).", "example": "uk-UA" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Tags for organizing and filtering sessions.", "example": [ "resolved" ] }, "title": { "type": [ "string", "null" ], "description": "Human-readable title for the session.", "example": "Updated session title" } } }, "UpdateSkillRequest": { "type": "object", "description": "Request to update a skill", "properties": { "skill_md": { "type": [ "string", "null" ], "description": "Updated SKILL.md content (re-parses frontmatter)" }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SkillStatus", "description": "Update status" } ] } } }, "UpdateTaskWebhookRequest": { "type": "object", "description": "Request body for updating a task webhook.", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Enable or disable the webhook." }, "secret": { "type": [ "string", "null" ], "description": "Replace the signing secret. Pass null to remove the existing secret." }, "url": { "type": [ "string", "null" ], "description": "New target URL." } } }, "UpdateWorkspaceRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "User": { "type": "object", "description": "User response for listing", "required": [ "id", "email", "name", "roles", "created_at" ], "properties": { "auth_provider": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "email": { "type": "string" }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." }, "name": { "type": "string", "description": "Human-readable name. Safe to render in user-facing messages." }, "roles": { "type": "array", "items": { "type": "string" } } } }, "UserMcpConnectionResponse": { "type": "object", "description": "Current user's MCP OAuth connection to a preset in the selected organization.", "required": [ "provider", "server_id", "server_name", "server_url", "server_status", "connected_at" ], "properties": { "connected_at": { "type": "string", "format": "date-time", "description": "Time when the user authorized the connection.", "example": "2026-09-19T12:00:00Z" }, "provider": { "type": "string", "description": "Stored connection provider key used to revoke the grant.", "example": "mcp_oauth_01933b5a-0000-7000-8000-000000000001" }, "provider_username": { "type": [ "string", "null" ], "description": "Account name reported by the MCP OAuth provider, when available.", "example": "alex@example.com" }, "scopes": { "type": [ "string", "null" ], "description": "Space-delimited OAuth scopes granted to this connection, when available.", "example": "tools:read tools:execute" }, "server_id": { "type": "string", "description": "UUID of the MCP server preset associated with the connection.", "example": "01933b5a-0000-7000-8000-000000000001" }, "server_name": { "type": "string", "description": "Display name of the MCP server preset.", "example": "microsoft_learn" }, "server_status": { "type": "string", "description": "Current lifecycle status of the MCP server preset.", "example": "active" }, "server_url": { "type": "string", "description": "MCP server endpoint URL.", "example": "https://learn.microsoft.com/api/mcp" } } }, "UserMcpConnectionsResponse": { "type": "object", "description": "One page of the current user's MCP connections in the selected organization.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserMcpConnectionResponse" }, "description": "MCP connections in this page.", "example": [ { "connected_at": "2026-09-19T12:00:00Z", "provider": "mcp_oauth_01933b5a-0000-7000-8000-000000000001", "provider_username": "alex@example.com", "scopes": "tools:read tools:execute", "server_id": "01933b5a-0000-7000-8000-000000000001", "server_name": "microsoft_learn", "server_status": "active", "server_url": "https://learn.microsoft.com/api/mcp" } ] }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the final page.", "example": "01933b5a-0000-7000-8000-000000000002" } } }, "ValidateSkillRequest": { "type": "object", "description": "Request to validate a SKILL.md", "required": [ "skill_md" ], "properties": { "skill_md": { "type": "string", "description": "Full SKILL.md content to validate, including the YAML frontmatter and the markdown body.", "example": "---\nname: refund-policy\ndescription: Issue refunds inside the policy window.\n---\n\nUse this when a customer asks for a refund within 30 days of purchase." } } }, "Verbosity": { "type": "string", "description": "Verbosity level for models that support output-length control.\nWire values map 1:1 to the OpenAI `verbosity` request parameter:\n`low` (terse), `medium` (balanced, provider default), `high`\n(comprehensive). Independent of `ReasoningEffort`, which tunes the\namount of reasoning rather than the length of the final answer.", "enum": [ "low", "medium", "high" ] }, "VerbosityConfig": { "type": "object", "description": "Verbosity configuration for a model", "required": [ "values", "default" ], "properties": { "default": { "$ref": "#/components/schemas/Verbosity", "description": "Default verbosity for this model" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/VerbosityValue" }, "description": "Available verbosity values for this model" } } }, "VerbosityValue": { "type": "object", "description": "Named verbosity value for UI display", "required": [ "value", "name" ], "properties": { "name": { "type": "string", "description": "Display name (e.g., \"Low\", \"High\")" }, "value": { "$ref": "#/components/schemas/Verbosity", "description": "The API value (e.g., \"low\", \"high\")" } } }, "VerificationStatus": { "type": "string", "description": "Whether a cited source entails the claim it is attached to.", "enum": [ "entailed", "unsupported", "uncertain" ], "example": "entailed" }, "VerificationVerdict": { "type": "object", "description": "Outcome of citation verification (see the `citation_verification` capability).", "required": [ "status" ], "properties": { "score": { "type": [ "number", "null" ], "format": "float", "description": "Entailment confidence in `[0, 1]`, when the verifier produced one.", "example": 0.92 }, "status": { "$ref": "#/components/schemas/VerificationStatus", "description": "Whether the cited source supports the claim." } } }, "VoiceAttachRequest": { "allOf": [ { "$ref": "#/components/schemas/VoiceSessionOptions" }, { "type": "object", "required": [ "provider_call_id" ], "properties": { "provider_call_id": { "type": "string" } } } ], "description": "Request body for voice attach." }, "VoiceAttachResponse": { "type": "object", "description": "Response body for voice attach.", "required": [ "voice_connection_id", "provider_call_id", "provider", "model", "voice", "reasoning_effort", "expires_at" ], "properties": { "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the connection's lease expires (RFC 3339)." }, "model": { "type": "string", "description": "Provider-side model identifier used for the realtime session." }, "provider": { "type": "string", "description": "Realtime provider routing this connection." }, "provider_call_id": { "type": "string", "description": "Provider-side call identifier of the connected realtime call." }, "reasoning_effort": { "type": "string", "description": "Reasoning effort tier for thinking-capable models." }, "voice": { "type": "string", "description": "Realtime voice preset selected for the connection." }, "voice_connection_id": { "type": "string", "description": "Prefixed public identifier of the voice connection. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." } } }, "VoiceCallRequest": { "allOf": [ { "$ref": "#/components/schemas/VoiceSessionOptions" }, { "type": "object", "required": [ "sdp" ], "properties": { "sdp": { "type": "string" } } } ], "description": "Request body for voice call." }, "VoiceCallResponse": { "type": "object", "description": "Response body for voice call.", "required": [ "voice_connection_id", "provider", "model", "voice", "reasoning_effort", "expires_at", "answer_sdp" ], "properties": { "answer_sdp": { "type": "string", "description": "Server-generated SDP answer to send back to the client to complete the WebRTC handshake." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the call's lease expires (RFC 3339)." }, "model": { "type": "string", "description": "Provider-side model identifier used for the realtime session." }, "provider": { "type": "string", "description": "Realtime provider routing this connection." }, "provider_call_id": { "type": [ "string", "null" ], "description": "Provider-side call identifier once issued. `None` until the realtime call is established." }, "reasoning_effort": { "type": "string", "description": "Reasoning effort tier for thinking-capable models." }, "voice": { "type": "string", "description": "Realtime voice preset selected for the connection." }, "voice_connection_id": { "type": "string", "description": "Prefixed public identifier of the voice connection. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." } } }, "VoiceClientSecretRequest": { "allOf": [ { "$ref": "#/components/schemas/VoiceSessionOptions" } ], "description": "Request body for voice client secret." }, "VoiceClientSecretResponse": { "type": "object", "description": "Response body for voice client secret.", "required": [ "voice_connection_id", "provider", "model", "voice", "reasoning_effort", "expires_at", "client_secret" ], "properties": { "client_secret": { "description": "Provider-specific ephemeral credential payload the client uses to authenticate the realtime connection." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the client secret expires (RFC 3339). The client must establish the realtime connection before this." }, "model": { "type": "string", "description": "Provider-side model identifier used for the realtime session." }, "provider": { "type": "string", "description": "Realtime provider routing this connection (e.g. `openai`)." }, "reasoning_effort": { "type": "string", "description": "Reasoning effort tier for thinking-capable models (`none`, `minimal`, `low`, `medium`, `high`)." }, "voice": { "type": "string", "description": "Realtime voice preset selected for the connection (provider-specific)." }, "voice_connection_id": { "type": "string", "description": "Prefixed public identifier of the voice connection. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." } } }, "VoiceEndRequest": { "type": "object", "description": "Request body for voice end.", "properties": { "reason": { "type": [ "string", "null" ], "description": "Free-text reason recorded with the session-ended event. Useful for operator forensics.", "example": "User hung up after refund confirmed." } } }, "VoiceEndResponse": { "type": "object", "description": "Response body for voice end.", "required": [ "voice_connection_id", "status" ], "properties": { "status": { "type": "string", "description": "Current lifecycle status." }, "voice_connection_id": { "type": "string", "description": "Prefixed public identifier of the voice connection that was ended." } } }, "VoiceSessionEndedData": { "type": "object", "description": "Data for voice.session.ended.", "required": [ "voice_connection_id" ], "properties": { "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Total wall-clock duration of the connection in milliseconds. `None` when the connection\nnever completed an audio handshake.", "example": 184500, "minimum": 0 }, "reason": { "type": [ "string", "null" ], "description": "Free-text end reason captured from the client or server. `None` when no reason was supplied.", "example": "User hung up after refund confirmed." }, "voice_connection_id": { "type": "string", "description": "Prefixed voice connection identifier for the ended session.", "example": "voice_01933b5a00007000800000000000001" } } }, "VoiceSessionFailedData": { "type": "object", "description": "Data for voice.session.failed.", "required": [ "voice_connection_id", "error" ], "properties": { "error": { "type": "string", "description": "Error message captured at failure. Provider-formatted; not stable for parsing.", "example": "realtime provider closed stream: 1011 internal_error" }, "voice_connection_id": { "type": "string", "description": "Prefixed voice connection identifier for the failed session.", "example": "voice_01933b5a00007000800000000000001" } } }, "VoiceSessionOptions": { "type": "object", "description": "Realtime-session knobs flattened into the voice request bodies that\ncreate or attach a realtime connection — `VoiceClientSecretRequest`,\n`VoiceCallRequest`, and `VoiceAttachRequest`. The `/voice/.../end`\nendpoint takes `VoiceEndRequest` and does not accept these options.\nAll fields are optional; omitted ones fall back to the agent's or\nprovider's default.", "properties": { "instructions": { "type": [ "string", "null" ], "description": "Extra system instructions appended to the realtime session prompt.", "example": "Always confirm before placing an order." }, "model": { "type": [ "string", "null" ], "description": "Provider-side realtime model identifier. When omitted the server picks the agent's configured default.", "example": "gpt-realtime" }, "provider_id": { "type": [ "string", "null" ], "description": "Realtime provider binding: the prefixed public id of the provider\nconnection to route this voice connection through (e.g. `prov_…`). Lets\nan org with more than one realtime-capable provider pick which one serves\nthe connection. When omitted, the server resolves the org's default (or\nsingle) realtime provider. The bound provider's driver MUST declare the\nrealtime service, otherwise the request is rejected with 400.", "example": "prov_01h…" }, "reasoning_effort": { "type": [ "string", "null" ], "description": "Reasoning effort hint passed through to the realtime model. One of `low`, `medium`, `high`.\nWhen omitted the server picks the provider's default.", "example": "medium" }, "voice": { "type": [ "string", "null" ], "description": "Realtime voice preset (provider-specific). When omitted the server picks the agent's configured default.", "example": "alloy" } } }, "VoiceSessionResponse_VoiceCallResponse": { "type": "object", "description": "Generic envelope returned by the agent/chat voice-session endpoints that\ncreate-or-attach a session and a voice connection in one round trip.\n`T` is the per-endpoint voice payload (`VoiceCallResponse`,\n`VoiceAttachResponse`).", "required": [ "session", "voice" ], "properties": { "session": { "$ref": "#/components/schemas/Session", "description": "The session this voice connection is attached to. Returned alongside\nthe voice payload so a caller has a single round-trip view of both." }, "voice": { "type": "object", "description": "Response body for voice call.", "required": [ "voice_connection_id", "provider", "model", "voice", "reasoning_effort", "expires_at", "answer_sdp" ], "properties": { "answer_sdp": { "type": "string", "description": "Server-generated SDP answer to send back to the client to complete the WebRTC handshake." }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the call's lease expires (RFC 3339)." }, "model": { "type": "string", "description": "Provider-side model identifier used for the realtime session." }, "provider": { "type": "string", "description": "Realtime provider routing this connection." }, "provider_call_id": { "type": [ "string", "null" ], "description": "Provider-side call identifier once issued. `None` until the realtime call is established." }, "reasoning_effort": { "type": "string", "description": "Reasoning effort tier for thinking-capable models." }, "voice": { "type": "string", "description": "Realtime voice preset selected for the connection." }, "voice_connection_id": { "type": "string", "description": "Prefixed public identifier of the voice connection. See [ID Schema](https://docs.everruns.com/advanced/id-schema/)." } } } } }, "VoiceSessionStartedData": { "type": "object", "description": "Data for voice.session.started.", "required": [ "voice_connection_id", "model", "voice", "reasoning_effort", "transport" ], "properties": { "model": { "type": "string", "description": "Provider-side realtime model identifier negotiated for this session.", "example": "gpt-realtime" }, "reasoning_effort": { "type": "string", "description": "Reasoning effort applied to the realtime model. One of `low`, `medium`, `high`.", "example": "medium" }, "transport": { "type": "string", "description": "Transport carrying the audio stream. One of `webrtc`, `sip`, `websocket`.", "example": "webrtc" }, "voice": { "type": "string", "description": "Realtime voice preset selected for this session.", "example": "alloy" }, "voice_connection_id": { "type": "string", "description": "Prefixed voice connection identifier for the started session.", "example": "voice_01933b5a00007000800000000000001" } } }, "VoiceTranscriptData": { "type": "object", "description": "Data for voice transcript delta/completed events.", "required": [ "voice_connection_id", "accumulated" ], "properties": { "accumulated": { "type": "string", "description": "Full transcript accumulated for this item up to and including `delta`." }, "delta": { "type": "string", "description": "Newly transcribed text chunk delivered in this event. Empty for \"final\" events that only mark completion." }, "item_id": { "type": [ "string", "null" ], "description": "Provider-specific identifier of the conversation item being transcribed. `None` when not yet assigned." }, "phase": { "type": [ "string", "null" ], "description": "Transcript phase: `user_partial`, `user_final`, `assistant_partial`, `assistant_final`. `None` when not yet classified." }, "response_id": { "type": [ "string", "null" ], "description": "Provider-specific identifier of the response stream emitting this transcript. `None` for user-side transcripts." }, "voice_connection_id": { "type": "string", "description": "Prefixed voice connection identifier this transcript belongs to." } } }, "WebhookInvocationResponse": { "type": "object", "description": "Response body for webhook invocation.", "required": [ "accepted", "session_id", "created_session" ], "properties": { "accepted": { "type": "boolean" }, "created_session": { "type": "boolean" }, "session_id": { "type": "string", "description": "Session's prefixed public identifier." } } }, "WithUrls_Agent": { "allOf": [ { "type": "object", "description": "Agent configuration for agentic loop.\nAn agent defines the behavior and capabilities of an AI assistant.", "required": [ "id", "name", "system_prompt", "harness_id", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the agent was archived.", "example": "2026-05-26T00:00:00Z" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities enabled for this agent with per-agent configuration.\nCapabilities add tools and system prompt modifications." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was created.", "example": "2026-04-01T10:00:00Z" }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model ID for this agent.\nCan be overridden at the session level.", "example": "model_01933b5a00007000800000000000001" }, "default_version_id": { "type": [ "string", "null" ], "description": "Default immutable version used by deployments that choose the default policy.", "example": "agentver_01933b5a00007000800000000000001" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the agent was deleted.", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the agent does.", "example": "Handles refund and shipping questions; escalates billing disputes." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI (e.g. \"Customer Support Agent\").\nFalls back to `name` when absent.", "example": "Customer Support Agent" }, "exposed": { "type": "boolean", "description": "Whether any endpoint on this agent is currently live. Derived from the\nendpoint rows on read and never stored: a stored flag would be a second\nwriter for state the endpoints already own." }, "exposures_suspended": { "type": "boolean", "description": "Incident switch: when true, no endpoint on this agent accepts traffic\n(EVE-1007). Distinct from archiving — it leaves per-endpoint status\nuntouched so clearing it restores exactly the previously live set." }, "forked_from_agent_id": { "type": [ "string", "null" ], "description": "Source agent for a forked agent.", "example": "agent_01933b5a00007000800000000000001" }, "forked_from_version_id": { "type": [ "string", "null" ], "description": "Source version for a forked agent.", "example": "agentver_01933b5a00007000800000000000001" }, "harness_id": { "type": "string", "description": "Harness that supplies the base execution environment for this agent.", "example": "harness_01933b5a00007000800000000000001" }, "id": { "type": "string", "description": "External identifier (agent_<32-hex>). Shown as \"id\" in API.\nClient-supplied or auto-generated.", "example": "agent_01933b5a000070008000000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this agent." }, "intro_markdown": { "type": [ "string", "null" ], "description": "Optional Markdown intro rendered as an intro box at the top of a fresh\nPlatform Chat thread. Images are allowed. Wins over the harness intro.\nHidden once the user inputs.", "example": "Hey, I'm Ava. Ask me anything about your account." }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this agent.", "example": 50, "minimum": 0 }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this agent and inherited by its sessions." }, "name": { "type": "string", "description": "Name, unique per org (e.g. \"customer-support\").", "example": "customer-support" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs agent sessions can reach.\nMerged with harness and session layers (allowed: intersect, blocked: union)." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "root_agent_id": { "type": [ "string", "null" ], "description": "Root agent lineage identifier for grouping fork families.", "example": "agent_01933b5a00007000800000000000001" }, "short_description": { "type": [ "string", "null" ], "description": "Optional one-line description in simplified Markdown, shown below the\nchat title once the intro is hidden. Wins over the harness value.", "example": "Answers account questions in seconds." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. Win over the\nharness starters when non-empty." }, "status": { "$ref": "#/components/schemas/AgentStatus", "description": "Current lifecycle status of the agent." }, "system_prompt": { "type": "string", "description": "System prompt that defines the agent's behavior.\nSent as the first message in every conversation.", "example": "You are a friendly customer support agent for Acme Corp. Verify orders before issuing refunds. Escalate any billing disputes to a human." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering agents.", "example": [ "support", "production" ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools registered for this agent.\nThese tools are executed by the client, not the server." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the agent was last updated.", "example": "2026-05-20T14:00:00Z" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative token usage across all sessions for this agent." } ] } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`.", "x-sdk-response-wrapper": { "kind": "resource", "model": "#/components/schemas/Agent" } }, "WithUrls_AgentWithCounts": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/Agent" }, { "type": "object", "required": [ "session_count", "app_count", "effective_harness" ], "properties": { "app_count": { "type": "integer", "format": "int64", "minimum": 0 }, "effective_harness": { "$ref": "#/components/schemas/AgentHarnessSummary" }, "session_count": { "type": "integer", "format": "int64", "minimum": 0 } } } ], "description": "Agent list/detail payload with relationship counts and resolved harness metadata." }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`.", "x-sdk-response-wrapper": { "kind": "resource", "model": "#/components/schemas/Agent" } }, "WithUrls_App": { "allOf": [ { "type": "object", "description": "App configuration for deploying agents to channels.\nAn app binds a harness and optional agent to distribution channels with a\npublish lifecycle.", "required": [ "id", "name", "harness_id", "owner_principal_id", "status", "created_at", "updated_at" ], "properties": { "agent_id": { "type": [ "string", "null" ], "description": "Optional ID of the agent to use (format: agent_{32-hex}).", "example": "agent_01933b5a00007000800000000000001" }, "agent_identity_id": { "type": [ "string", "null" ], "description": "Optional virtual identity that represents the app in unattended/channel execution.", "example": "identity_01933b5a00007000800000000000001" }, "agent_version_id": { "type": [ "string", "null" ], "description": "Pinned agent version. Required when policy is `pinned`.", "example": "agentver_01933b5a00007000800000000000001" }, "agent_version_policy": { "$ref": "#/components/schemas/AgentVersionPolicy", "description": "Version resolution policy for the optional agent." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the app was archived." }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/AppChannel" }, "description": "Distribution channels attached to this app." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the app was created." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the app was deleted." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the app does." }, "effective_owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Effective human owner summary." } ] }, "harness_id": { "type": "string", "description": "ID of the harness to use (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "id": { "type": "string", "description": "External identifier (app_<32-hex>). Shown as \"id\" in API.", "example": "app_01933b5a000070008000000000000001" }, "name": { "type": "string", "description": "Display name of the app." }, "owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Owning principal summary." } ] }, "owner_principal_id": { "type": "string", "description": "Owning principal for this app.", "example": "principal_01933b5a000070008000000000000001" }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the app was last published." }, "resolved_owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Denormalized effective human owner of the owning principal lineage." }, "status": { "$ref": "#/components/schemas/AppStatus", "description": "Current lifecycle status." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the app was last updated." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "WithUrls_CapabilityInfo": { "allOf": [ { "type": "object", "description": "Public capability information (without internal details)\nThis is what gets returned from the API\nNamed CapabilityInfo to distinguish from the Capability trait", "required": [ "id", "name", "description", "status" ], "properties": { "agent_count": { "type": "integer", "format": "int64", "description": "Number of active agents referencing this capability in the org.", "example": 42, "minimum": 0 }, "category": { "type": [ "string", "null" ], "description": "Category for grouping in UI", "example": "filesystem" }, "config_schema": { "type": "object", "description": "JSON Schema for capability-specific per-agent config." }, "config_ui_schema": { "type": "object", "description": "react-jsonschema-form uiSchema hints for rendering config_schema." }, "dependencies": { "type": "array", "items": { "type": "string" }, "description": "IDs of capabilities that this capability depends on.\nWhen this capability is selected, its dependencies are automatically included.", "example": [ "approval" ] }, "description": { "type": "string", "description": "Description of what this capability provides", "example": "Read, write, edit, list, grep, delete, and stat files in the session workspace." }, "docs_slug": { "type": [ "string", "null" ], "description": "Slug under https://dev.everruns.com/capabilities/ when public docs exist.", "example": "session_file_system" }, "features": { "type": "array", "items": { "type": "string" }, "description": "UI feature strings this capability contributes to.\nMultiple capabilities can contribute the same feature.", "example": [ "file_browser" ] }, "harness_count": { "type": "integer", "format": "int64", "description": "Number of active harnesses referencing this capability in the org.", "example": 7, "minimum": 0 }, "icon": { "type": [ "string", "null" ], "description": "Icon name (for UI rendering)", "example": "Folder" }, "id": { "type": "string", "description": "Unique capability identifier", "example": "session_file_system" }, "is_guardrail": { "type": "boolean", "description": "Whether this capability is a guardrail (constrains agent behavior\nrather than granting abilities). Used for UI grouping and filtering.", "example": false }, "is_mcp": { "type": "boolean", "description": "Whether this is an MCP server capability (for UI badge)", "example": false }, "is_skill": { "type": "boolean", "description": "Whether this is an Agent Skill capability (for UI badge)", "example": false }, "localizations": { "type": "object", "description": "Localized display strings keyed by lowercase language tag (e.g. \"uk\").\nThe \"en\" entry carries only `config_description`, since the base\nname/description/config_schema strings are already English.", "additionalProperties": { "$ref": "#/components/schemas/CapabilityLocalizationInfo" }, "propertyNames": { "type": "string" }, "example": { "uk": { "description": "Монтує спільні файли пам'яті в сесії.", "name": "Пам'ять" } } }, "name": { "type": "string", "description": "Display name", "example": "Session File System" }, "risk_level": { "$ref": "#/components/schemas/RiskLevel", "description": "TM-AGENT-005: Risk level. High-risk capabilities require admin approval." }, "status": { "type": "string", "description": "Current status", "example": "active" }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt addition contributed by this capability", "example": "You can read and write files in /workspace via the session_file_system tools." }, "tool_definitions": { "type": "array", "items": { "type": "object" }, "description": "Tool definitions provided by this capability", "example": [ { "description": "Read a file from the session workspace.", "name": "read_file" }, { "description": "Write or overwrite a file in the session workspace.", "name": "write_file" } ] } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`.", "x-sdk-response-wrapper": { "kind": "resource", "model": "#/components/schemas/CapabilityInfo" } }, "WithUrls_DeclarativeCapability": { "allOf": [ { "type": "object", "description": "Persisted, org-scoped declarative capability — a YAML/JSON-defined\nbundle of skills, files, and tool defs that an agent or harness can\nreference by `capability_id` or name.", "required": [ "id", "capability_id", "name", "description", "status", "definition", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was archived, if any (RFC 3339)." }, "capability_id": { "type": "string", "description": "Runtime capability reference. Agents and harnesses may use this or the plain unique name.", "example": "declarative:research_pack" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "definition": { "type": "object", "description": "Declarative capability payload: system prompt, skills, starter files, MCP servers, and metadata." }, "definition_error": { "type": [ "string", "null" ], "description": "Why the stored definition could not be parsed, when it could not be.\n\nPresent only for a corrupt row. The capability keeps its identity\ncolumns so a surface can name what is broken, but `definition` is the\ninert default and `definition.status` reports `retired`, so nothing\nreads it as a usable capability.", "example": "missing field `acts_as` at line 1 column 84" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource was soft-deleted, if any (RFC 3339)." }, "description": { "type": "string", "description": "Short summary shown in pickers, search results, and API listings.", "example": "Adds research instructions, starter files, and MCP tools." }, "display_name": { "type": [ "string", "null" ], "description": "Human-facing label shown in the UI. Defaults to `name` when omitted.", "example": "Research Pack" }, "id": { "type": "string", "description": "Public resource ID for this persisted declarative capability.", "example": "cap_01933b5a000070008000000000000001" }, "name": { "type": "string", "description": "Stable unique name used in capability refs. Lowercase letters, numbers, and underscores.", "example": "research_pack" }, "status": { "type": "string", "description": "Lifecycle state for the resource: active, disabled, archived, or deleted.", "example": "active" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was last updated (RFC 3339)." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "WithUrls_Harness": { "allOf": [ { "type": "object", "description": "Harness configuration for sessions.\nA harness defines the base behavior and capabilities that apply to all sessions.", "required": [ "id", "name", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was archived.", "example": "2026-05-26T00:00:00Z" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities enabled for this harness with per-harness configuration." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was created.", "example": "2026-04-01T10:00:00Z" }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model ID for this harness.\nLowest priority in chain: controls > session > agent > harness.", "example": "model_01933b5a00007000800000000000001" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was deleted.", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the harness does.", "example": "Default harness with file-system + secrets capabilities; safe baseline for new agents." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI.", "example": "Generic Harness" }, "embedder_metadata": { "type": "object", "description": "Arbitrary key-value metadata injected into LLM requests for observability.\nKeys from system context (session_id, org_id, etc.) always take precedence.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": { "env": "production", "team": "platform" } }, "icon": { "type": [ "string", "null" ], "description": "Display glyph name rendered by the UI (e.g. \"message-circle\").\n\nBuilt-in harnesses declare it in their definition; custom harnesses\nleave it unset and fall back to the UI's generic harness glyph.", "example": "message-circle" }, "id": { "type": "string", "description": "Unique identifier for the harness (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this harness." }, "intro_markdown": { "type": [ "string", "null" ], "description": "Optional Markdown intro rendered as an intro box at the top of a fresh\nPlatform Chat thread. Images are allowed. The agent intro wins over\nthe harness intro. Hidden once the user inputs.", "example": "I can triage incidents, dig through logs, and draft the update." }, "is_built_in": { "type": "boolean", "description": "Whether this harness is built-in (system-managed, readonly).\nBuilt-in harnesses are provisioned during org initialization and\ncannot be modified or deleted via the API. Users can copy them.", "example": false }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this harness and inherited by descendant layers." }, "name": { "type": "string", "description": "Name, unique per org (e.g. \"generic\").", "example": "generic" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs sessions can reach.\nMerged with agent and session layers (allowed: intersect, blocked: union)." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "parent_harness_id": { "type": [ "string", "null" ], "description": "Optional parent harness that this harness inherits from.", "example": "harness_01933b5a000070008000000000000602" }, "short_description": { "type": [ "string", "null" ], "description": "Optional one-line description in simplified Markdown, shown below the\nchat title once the intro is hidden. The agent value wins.", "example": "Knows your agents, harnesses, models, and runs." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. The agent's\nstarters win when non-empty, otherwise the harness's apply." }, "status": { "$ref": "#/components/schemas/HarnessStatus", "description": "Current lifecycle status of the harness." }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt that defines the harness's base behavior.\n\nForms the foundation of the prompt stack. Optional: when absent the\nharness contributes no base prompt, so the effective prompt comes\nentirely from the parent harness (if any), the agent, the session, and\ncapability contributions. Empty/whitespace-only values normalize to\n`None`.", "example": "You are an Everruns agent. Be concise, cite sources when possible, and decline tasks outside your assigned scope." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering harnesses.", "example": [ "baseline", "production" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was last updated.", "example": "2026-05-20T14:00:00Z" } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "WithUrls_McpServer": { "allOf": [ { "type": "object", "description": "MCP Server configuration.\nRepresents a remote MCP server that can provide tools and resources.", "required": [ "id", "name", "url", "transport_type", "status", "api_key_set", "created_at", "updated_at" ], "properties": { "api_key_set": { "type": "boolean", "description": "Whether an API key has been configured." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the MCP server was archived." }, "auth_mode": { "$ref": "#/components/schemas/McpServerAuthMode", "description": "Authentication mode for this MCP server." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the MCP server was created." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the MCP server was deleted." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the MCP server.", "example": "Atlassian MCP Server for Jira and Confluence" }, "headers": { "type": "object", "description": "Additional HTTP headers for authentication.\nKeys are header names, values are header values.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Unique identifier for the MCP server.", "example": "mcp_01933b5a00007000800000000000001" }, "name": { "type": "string", "description": "Display name of the MCP server.", "example": "atlassian-mcp-server" }, "oauth_provider_id": { "type": [ "string", "null" ], "description": "Stable provider id used for user-scoped OAuth connections." }, "protocol_mode": { "$ref": "#/components/schemas/McpProtocolMode", "description": "Protocol-era adoption policy for the MCP client (`auto` negotiates)." }, "status": { "$ref": "#/components/schemas/McpServerStatus", "description": "Current lifecycle status of the MCP server." }, "transport_type": { "$ref": "#/components/schemas/McpServerTransportType", "description": "Transport type (currently only HTTP supported)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the MCP server was last updated." }, "url": { "type": "string", "description": "URL of the MCP server endpoint.", "example": "https://mcp.atlassian.com/v1/mcp" } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "WithUrls_Model": { "allOf": [ { "type": "object", "description": "LLM Model entity", "required": [ "id", "provider_id", "model_id", "display_name", "capabilities", "is_favorite", "enabled", "source", "created_at", "updated_at" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability tags supported by this model (e.g. `chat`, `tools`, `vision`)." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was created (RFC 3339)." }, "display_name": { "type": "string", "description": "Human-readable display name. Safe to render in user-facing messages." }, "enabled": { "type": "boolean", "description": "Whether this model is selectable. Controls UI visibility AND server-side resolution: `ProviderResolverService` requires `enabled = true`, and org default-model validation rejects disabled models. Disabled models stay visible in raw list endpoints (so admins can re-enable them) but cannot be used in active sessions or as a session/agent default." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "model_01933b5a00007000800000000000001" }, "is_favorite": { "type": "boolean", "description": "Whether this model is starred in the UI for quick access." }, "model_id": { "type": "string", "description": "Provider-side model identifier as sent on the wire (e.g. `gpt-5.2`, `claude-sonnet-5`)." }, "provider_id": { "type": "string", "description": "Owning provider's prefixed public identifier.", "example": "provider_01933b5a00007000800000000000001" }, "source": { "$ref": "#/components/schemas/ModelSource", "description": "How this model entry was added (manually, discovered, or seeded as predefined)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was last updated (RFC 3339)." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "WithUrls_ModelWithProvider": { "allOf": [ { "type": "object", "description": "LLM Model with provider info", "required": [ "id", "provider_id", "model_id", "display_name", "capabilities", "is_favorite", "enabled", "source", "created_at", "updated_at", "provider_name", "provider_type", "healthy" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capability tags supported by this model.", "example": [ "text", "tools", "vision", "thinking" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was created (RFC 3339).", "example": "2026-01-04T11:23:00Z" }, "display_name": { "type": "string", "description": "Human-readable display name.", "example": "Claude Sonnet 4.5" }, "enabled": { "type": "boolean", "description": "Whether this model is selectable. Controls UI visibility AND server-side resolution: `ProviderResolverService` requires `enabled = true`, and org default-model validation rejects disabled models.", "example": true }, "healthy": { "type": "boolean", "description": "Derived: model is configured and ready for use. Currently means the\njoined provider is active and has an API key set; over time this may\nalso incorporate live reachability checks. Not persisted.", "example": true }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "model_01933b5a00007000800000000000001" }, "is_favorite": { "type": "boolean", "description": "Whether this model is starred in the UI for quick access.", "example": true }, "model_id": { "type": "string", "description": "Provider-side model identifier as sent on the wire (e.g. `gpt-5.2`).", "example": "claude-sonnet-4-5" }, "model_vendor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelVendor", "description": "Vendor/brand of the model, derived from the model registry. Drives UI\nbranding (icons). `None` when the model id is not in the registry. Not persisted." } ] }, "profile": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelProfile", "description": "Readonly profile with model capabilities (limits, pricing, modalities). Not persisted." } ] }, "provider_id": { "type": "string", "description": "Owning provider's prefixed public identifier.", "example": "provider_01933b5a00007000800000000000001" }, "provider_name": { "type": "string", "description": "Joined provider display name.", "example": "Anthropic" }, "provider_type": { "$ref": "#/components/schemas/DriverId", "description": "Joined provider implementation type." }, "source": { "$ref": "#/components/schemas/ModelSource", "description": "How this model entry was added (manually, discovered, or seeded as predefined)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this model was last updated (RFC 3339).", "example": "2026-05-27T15:24:00Z" } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "WithUrls_Provider": { "allOf": [ { "type": "object", "description": "LLM Provider entity (API keys never exposed)\nNote: This is the entity struct, separate from the Provider trait in llm.rs", "required": [ "id", "name", "provider_type", "api_key_set", "status", "managed", "created_at", "updated_at" ], "properties": { "api_key_set": { "type": "boolean", "description": "Whether an API key is configured. The key itself is never returned." }, "base_url": { "type": [ "string", "null" ], "description": "Custom base URL for self-hosted / proxied providers. `None` means use the provider's default endpoint." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this provider was created (RFC 3339)." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "provider_01933b5a00007000800000000000001" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent successful model sync from the provider's API (RFC 3339)." }, "managed": { "type": "boolean", "description": "Whether this provider is host-managed (EVE-810). A managed provider is\nprovisioned by the host/embedder; the OSS API rejects tenant PATCH/DELETE\non it (403). Read-only to org admins. Defaults to `false`." }, "name": { "type": "string", "description": "Human-readable provider name. Safe to render in user-facing messages." }, "provider_type": { "$ref": "#/components/schemas/DriverId", "description": "Provider implementation type (OpenAI, Anthropic, Gemini, etc.)." }, "request_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderRequestOptions", "description": "Extra headers and diagnostics options applied to every request sent to\nthis provider. `None` when the org configured nothing." } ] }, "status": { "$ref": "#/components/schemas/ProviderStatus", "description": "Current lifecycle status of this provider." }, "trace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProviderTraceConfig", "description": "Resolved trace/observability link configuration: the driver's default\ntemplates overlaid with this provider's stored overrides. `None` when the\ndriver exposes no dashboard and the org configured nothing." } ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this provider was last updated (RFC 3339)." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "WithUrls_ResourceWithCounts_Harness": { "allOf": [ { "allOf": [ { "type": "object", "description": "Harness configuration for sessions.\nA harness defines the base behavior and capabilities that apply to all sessions.", "required": [ "id", "name", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was archived.", "example": "2026-05-26T00:00:00Z" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Capabilities enabled for this harness with per-harness configuration." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was created.", "example": "2026-04-01T10:00:00Z" }, "default_model_id": { "type": [ "string", "null" ], "description": "Default LLM model ID for this harness.\nLowest priority in chain: controls > session > agent > harness.", "example": "model_01933b5a00007000800000000000001" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the harness was deleted.", "example": "2026-05-26T00:00:00Z" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of what the harness does.", "example": "Default harness with file-system + secrets capabilities; safe baseline for new agents." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable display name shown in UI.", "example": "Generic Harness" }, "embedder_metadata": { "type": "object", "description": "Arbitrary key-value metadata injected into LLM requests for observability.\nKeys from system context (session_id, org_id, etc.) always take precedence.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": { "env": "production", "team": "platform" } }, "icon": { "type": [ "string", "null" ], "description": "Display glyph name rendered by the UI (e.g. \"message-circle\").\n\nBuilt-in harnesses declare it in their definition; custom harnesses\nleave it unset and fall back to the UI's generic harness glyph.", "example": "message-circle" }, "id": { "type": "string", "description": "Unique identifier for the harness (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Starter files copied into each new session for this harness." }, "intro_markdown": { "type": [ "string", "null" ], "description": "Optional Markdown intro rendered as an intro box at the top of a fresh\nPlatform Chat thread. Images are allowed. The agent intro wins over\nthe harness intro. Hidden once the user inputs.", "example": "I can triage incidents, dig through logs, and draft the update." }, "is_built_in": { "type": "boolean", "description": "Whether this harness is built-in (system-managed, readonly).\nBuilt-in harnesses are provisioned during org initialization and\ncannot be modified or deleted via the API. Users can copy them.", "example": false }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this harness and inherited by descendant layers." }, "name": { "type": "string", "description": "Name, unique per org (e.g. \"generic\").", "example": "generic" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs sessions can reach.\nMerged with agent and session layers (allowed: intersect, blocked: union)." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "parent_harness_id": { "type": [ "string", "null" ], "description": "Optional parent harness that this harness inherits from.", "example": "harness_01933b5a000070008000000000000602" }, "short_description": { "type": [ "string", "null" ], "description": "Optional one-line description in simplified Markdown, shown below the\nchat title once the intro is hidden. The agent value wins.", "example": "Knows your agents, harnesses, models, and runs." }, "starters": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationStarter" }, "description": "Conversation starters for a fresh Platform Chat thread. The agent's\nstarters win when non-empty, otherwise the harness's apply." }, "status": { "$ref": "#/components/schemas/HarnessStatus", "description": "Current lifecycle status of the harness." }, "system_prompt": { "type": [ "string", "null" ], "description": "System prompt that defines the harness's base behavior.\n\nForms the foundation of the prompt stack. Optional: when absent the\nharness contributes no base prompt, so the effective prompt comes\nentirely from the parent harness (if any), the agent, the session, and\ncapability contributions. Empty/whitespace-only values normalize to\n`None`.", "example": "You are an Everruns agent. Be concise, cite sources when possible, and decline tasks outside your assigned scope." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering harnesses.", "example": [ "baseline", "production" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the harness was last updated.", "example": "2026-05-20T14:00:00Z" } } }, { "type": "object", "required": [ "session_count", "app_count" ], "properties": { "app_count": { "type": "integer", "format": "int64", "description": "Number of non-deleted apps using this resource.", "minimum": 0 }, "session_count": { "type": "integer", "format": "int64", "description": "Number of sessions using this resource.", "minimum": 0 } } } ], "description": "Wrapper that flattens lightweight relationship counts into resource responses." }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "WithUrls_Session": { "allOf": [ { "type": "object", "description": "Session - instance of agentic loop execution.\nA session represents a single conversation with an agent.", "required": [ "id", "organization_id", "workspace_id", "harness_id", "owner_principal_id", "status", "created_at", "updated_at" ], "properties": { "active_schedule_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of active (enabled) schedules for this session.\nPopulated when the session is fetched for API responses.", "example": 2, "minimum": 0 }, "activity": { "$ref": "#/components/schemas/SessionActivity", "description": "Outcome-oriented status derived from `status` and the last turn result.\nThis is the value the sessions list groups by and the facet rail counts." }, "agent_id": { "type": [ "string", "null" ], "description": "ID of the agent working in this session (format: agent_{32-hex}). Optional.", "example": "agent_01933b5a00007000800000000000001" }, "agent_identity_id": { "type": [ "string", "null" ], "description": "Optional resident agent identity for unattended/background execution.", "example": "identity_01933b5a00007000800000000000001" }, "agent_version_id": { "type": [ "string", "null" ], "description": "Immutable agent version captured when the session was created or rebound.", "example": "agentver_01933b5a00007000800000000000001" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When this session was archived; `None` means active. Archived sessions\nare hidden from default list results and shown by opting in\n(`include_archived=true`). Unlike `is_pinned`, archive is a property of\nthe session itself rather than of the viewer.", "example": "2026-05-25T10:14:32Z" }, "blueprint_config": { "type": [ "object", "null" ], "description": "Validated config passed by host at blueprint spawn time.\nExample: `{\"target_repo\": \"acme/everruns\"}`." }, "blueprint_id": { "type": [ "string", "null" ], "description": "Blueprint ID. When set, reason_activity and act_activity build RuntimeAgent\nfrom the blueprint definition instead of from harness_id/agent_id.", "example": "blueprint_research_pack" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCapabilityConfig" }, "description": "Session-level capabilities (additive to agent capabilities).\nApplied after agent capabilities when building RuntimeAgent." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was created.", "example": "2026-05-25T10:00:00Z" }, "effective_owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Effective human owner summary." } ] }, "event_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Total events recorded for this session (EVE-868). Read from the\ndenormalized `sessions.event_count` counter rather than counted, so the\nsession detail tab bar costs no extra scan over `events`.\n`None` on payloads built outside the database read path.", "example": 42, "minimum": 0 }, "features": { "type": "array", "items": { "type": "string" }, "description": "Aggregated UI features from all active capabilities (harness + agent + session).\nComputed at read time from the capability registry.\nKnown features: \"file_system\", \"schedules\", \"secrets\", \"key_value\",\n\"sql_database\", \"leased_resources\".", "example": [ "file_system", "secrets" ] }, "file_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Non-directory files in this session's workspace (EVE-868). Read from\n`workspaces.file_count`. Counts persisted files only: capability-provided\nvirtual mounts are served from memory and are not included.", "example": 6, "minimum": 0 }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the session finished (completed or failed).", "example": "2026-05-25T10:14:32Z" }, "forked_from_sequence": { "type": [ "integer", "null" ], "format": "int32", "description": "Parent event sequence the fork was taken at (the fork point). NULL unless\nthis session is a fork.", "example": 42 }, "forked_from_session_id": { "type": [ "string", "null" ], "description": "Session this one was forked from. NULL for sessions that were not forked.\nDistinct from `parent_session_id` (subagent nesting): forking is a\nuser-initiated \"branch from here\" relationship." }, "goal": { "type": [ "string", "null" ], "description": "Session objective visible to the runtime agent at system-prompt level.", "example": "Investigate the queue latency regression" }, "harness_id": { "type": "string", "description": "ID of the harness for this session (format: harness_{32-hex}).", "example": "harness_01933b5a00007000800000000000001" }, "hints": { "type": [ "object", "null" ], "description": "Session-level client hints — arbitrary key-value pairs declared by the\nclient at session creation time. These are defaults for every turn;\nper-message `controls.hints` override these key-by-key (shallow merge).\n\nExamples: `{\"setup_connection\": true, \"rich_media\": true}`", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "id": { "type": "string", "description": "Unique identifier for the session (format: session_{32-hex}).", "example": "session_01933b5a00007000800000000000001" }, "initial_files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFile" }, "description": "Session-level initial files (additive to agent initial_files).\nFiles with matching paths override agent/harness files; new paths are appended." }, "is_pinned": { "type": [ "boolean", "null" ], "description": "Whether this session is pinned by the current user.\nOnly populated when the request has an authenticated user context.", "example": false }, "locale": { "type": [ "string", "null" ], "description": "Locale for localized agent behavior and formatting (BCP 47, e.g. `uk-UA`).", "example": "en-US" }, "max_iterations": { "type": [ "integer", "null" ], "description": "Maximum number of LLM iterations per turn for this session.", "example": 50, "minimum": 0 }, "mcpServers": { "$ref": "#/components/schemas/BTreeMap", "description": "Remote MCP servers scoped to this session only." }, "model_id": { "type": [ "string", "null" ], "description": "LLM model ID to use for this session (format: model_{32-hex}).\nOverrides the agent's default model if set.", "example": "model_01933b5a00007000800000000000001" }, "network_access": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkAccessList", "description": "Network access list controlling which hosts/URLs this session can reach.\nMerged with harness and agent layers (allowed: intersect, blocked: union)." } ] }, "organization_id": { "type": "string", "description": "Organization this session belongs to (format: org_{32-hex}).", "example": "org_00000000000000000000000000000001" }, "output_preview": { "type": [ "string", "null" ], "description": "Preview text from the last assistant response (truncated).", "example": "Here is a Q3 plan covering the three pillars we discussed..." }, "owner": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalSummary", "description": "Owning principal summary." } ] }, "owner_principal_id": { "type": "string", "description": "Owning principal for this session.", "example": "principal_01933b5a000070008000000000000001" }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Request-level parallel tool calling preference (EVE-598).\n\n`None` (default) preserves provider defaults. `Some(true)` signals the\nprovider that parallel tool calls are wanted; `Some(false)` requests at\nmost one tool call per turn and forces serial execution. Merged across\nharness/agent/session layers (overlay wins).", "example": true }, "parent_session_id": { "type": [ "string", "null" ], "description": "Parent session that spawned this subagent. NULL for top-level sessions.\nUsed to compute governed subagent delegation depth." }, "preview": { "type": [ "string", "null" ], "description": "Preview text from the first user message (truncated).", "example": "Help me draft the Q3 marketing plan" }, "resolved_owner_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Denormalized effective human owner of the owning principal lineage.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "run_summary": { "type": [ "string", "null" ], "description": "Generated one-sentence description of what the run did, and where it\nfailed (EVE-867). Absent until a terminal turn has been summarised, and\nalways absent for chat threads and for deployments with no utility LLM,\nso a reader must have a fallback rather than treating this as required.", "example": "Ran the nightly report and failed posting it to Slack: channel_not_found." }, "source": { "$ref": "#/components/schemas/SessionSource", "description": "How this session was started. Server-owned for every ingress path." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the session started executing.", "example": "2026-05-25T10:00:01Z" }, "status": { "$ref": "#/components/schemas/SessionStatus", "description": "Current execution status of the session." }, "system_prompt": { "type": [ "string", "null" ], "description": "Session-level system prompt override.\nPrepended to the agent's system prompt when building RuntimeAgent." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing and filtering sessions.", "example": [ "marketing", "q3", "draft" ] }, "task_count": { "type": [ "integer", "null" ], "format": "int32", "description": "Background work owned by this session — subagents, external agents and\nbackground tools (EVE-868). Read from `sessions.task_count`. This is\nwhat the Work tab holds; `active_schedule_count` describes only the\nschedules it also lists.", "example": 3, "minimum": 0 }, "title": { "type": [ "string", "null" ], "description": "Human-readable title for the session.", "example": "Q3 marketing brief" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Client-side tools for this session (additive to agent tools)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the session was last updated.", "example": "2026-05-25T10:14:32Z" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative token usage for all LLM calls in this session." } ] }, "workspace_id": { "type": "string", "description": "Workspace this session is attached to (format: wsp_{32-hex}). Owns the\nsession's virtual filesystem. For the default 1:1 case this mirrors the\nsession id, but clients should read it here rather than deriving it.", "example": "wsp_01933b5a00007000800000000000001" } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`.", "x-sdk-response-wrapper": { "kind": "resource", "model": "#/components/schemas/Session" } }, "WithUrls_Skill": { "allOf": [ { "type": "object", "description": "Skill entity (API response type)", "required": [ "id", "name", "description", "source_type", "status", "version", "created_at", "updated_at" ], "properties": { "allowed_tools": { "type": [ "string", "null" ], "description": "Comma-separated list of tool patterns this skill may invoke. `None` means inherit from the harness." }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this skill was archived, if any (RFC 3339). Archived skills are hidden from default list views." }, "compatibility": { "type": [ "string", "null" ], "description": "Compatibility marker describing host-runtime requirements declared by the skill (e.g. min platform version). Informational." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this skill was created (RFC 3339)." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this skill was hard-deleted, if any (RFC 3339)." }, "description": { "type": "string", "description": "Short, agent- and user-readable summary of what the skill does and when to use it.", "example": "Extract text and tables from PDF files." }, "disable_model_invocation": { "type": "boolean", "description": "When `true`, the LLM is prevented from auto-invoking this skill; only the user can trigger it explicitly." }, "id": { "type": "string", "description": "Prefixed public identifier. See [ID Schema](https://docs.everruns.com/advanced/id-schema/).", "example": "skill_01933b5a00007000800000000000001" }, "license": { "type": [ "string", "null" ], "description": "License string as declared by the skill author (e.g. `MIT`, `Apache-2.0`). Informational; not enforced." }, "metadata": { "type": "object", "description": "Free-form metadata declared by the skill author.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Stable kebab-case slug used to invoke the skill (e.g. `/pdf-processing` in chat). Safe to render in user-facing messages.", "example": "pdf-processing" }, "source_type": { "$ref": "#/components/schemas/SkillSourceType", "description": "How the skill content is sourced (filesystem, URL, embedded). Determines reload semantics." }, "status": { "$ref": "#/components/schemas/SkillStatus", "description": "Current lifecycle status (`active`, `archived`, `deleted`)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this skill was last updated (RFC 3339)." }, "user_invocable": { "type": "boolean", "description": "Whether this skill appears as a `/`-prefixed slash command for end users in chat UIs." }, "version": { "type": "string", "description": "Semver string declared by the skill author. Free-form; sorted lexicographically when comparing." } } }, { "type": "object", "required": [ "self_url", "view_url", "ui_link" ], "properties": { "allowed_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedAction" }, "description": "State-aware hypermedia actions the caller can take on this resource\nnext (e.g. `cancel`, `events`, `update`). Omitted from the wire\nshape when empty so resources that haven't opted into the\nconvention don't grow their payloads." }, "self_url": { "type": "string", "description": "Full API endpoint URL for this resource." }, "ui_link": { "type": "string", "description": "Alias for `view_url`, used by command and MCP outputs." }, "view_url": { "type": "string", "description": "Full UI URL for viewing this resource." } } } ], "description": "Wrapper that adds API and UI links to a serialized resource.\n\nUses `self_url` (not `url`) for the API link to avoid collision with\nresources that already have a `url` field (e.g. McpServer). The\n`allowed_actions` array carries state-aware hypermedia links — empty\n(and omitted from the wire shape) until the underlying resource opts\ninto the convention by overriding `ResourceUrlable::allowed_actions`." }, "WorkerResponse": { "type": "object", "description": "Worker response", "required": [ "id", "activity_types", "max_concurrency", "current_load", "status", "accepting_tasks", "started_at", "last_heartbeat_at", "tasks_completed", "tasks_failed" ], "properties": { "accepting_tasks": { "type": "boolean", "description": "Whether the worker is currently accepting new task assignments. Disabled briefly during drains or backpressure.", "example": true }, "activity_types": { "type": "array", "items": { "type": "string" }, "description": "Activity types this worker accepts. Tasks with other activity types skip this worker.", "example": [ "agent_loop", "tool_call" ] }, "avg_task_duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Average task duration in milliseconds across recent activity.", "example": 184, "minimum": 0 }, "backpressure_reason": { "type": [ "string", "null" ], "description": "Human-readable reason the worker is rejecting tasks, when `accepting_tasks` is `false`.", "example": "draining for deploy" }, "current_load": { "type": "integer", "format": "int32", "description": "Number of tasks currently executing on this worker.", "example": 3, "minimum": 0 }, "hostname": { "type": [ "string", "null" ], "description": "Hostname / pod name the worker is running on. Operator hint; not used for routing.", "example": "worker-prod-7c8b9d-r2x4p" }, "id": { "type": "string", "description": "Opaque durable worker identifier (defaults to `worker-`).", "example": "worker-7f3a9b2e-1c4d-4a5f-8b6c-9d0e1f2a3b4c" }, "last_heartbeat_at": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent heartbeat from this worker (RFC 3339).", "example": "2026-05-27T15:30:42Z" }, "max_concurrency": { "type": "integer", "format": "int32", "description": "Maximum number of tasks the worker will run concurrently.", "example": 8, "minimum": 0 }, "metadata": { "type": "object", "description": "Free-form worker-reported metadata (deployment, capabilities flag set, etc.)." }, "started_at": { "type": "string", "format": "date-time", "description": "Timestamp when this worker started accepting tasks (RFC 3339).", "example": "2026-05-27T08:00:00Z" }, "status": { "type": "string", "description": "Current lifecycle status (`running`, `draining`, `stopped`, etc.).", "example": "running" }, "tasks_completed": { "type": "integer", "format": "int64", "description": "Total tasks this worker has completed successfully.", "example": 12843, "minimum": 0 }, "tasks_failed": { "type": "integer", "format": "int64", "description": "Total tasks this worker has failed (including retries that were ultimately abandoned).", "example": 17, "minimum": 0 }, "version": { "type": [ "string", "null" ], "description": "Build version of the worker binary.", "example": "0.8.35" }, "worker_group": { "type": [ "string", "null" ], "description": "Logical group this worker belongs to (used for routing). `None` for ungrouped workers.", "example": "session-agents" } } }, "WorkersListResponse": { "type": "object", "description": "Workers list response", "required": [ "data", "total", "summary" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkerResponse" }, "description": "Page of items returned by this query." }, "summary": { "$ref": "#/components/schemas/WorkersSummaryResponse" }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages.", "minimum": 0 } } }, "WorkersSummaryResponse": { "type": "object", "description": "Workers summary stats", "required": [ "active", "draining", "stopped", "total_capacity", "total_load" ], "properties": { "active": { "type": "integer", "description": "Workers in `running` state, accepting tasks.", "minimum": 0 }, "draining": { "type": "integer", "description": "Workers in `draining` state, finishing in-flight tasks but not accepting new ones.", "minimum": 0 }, "stopped": { "type": "integer", "description": "Workers in `stopped` state, neither running nor draining.", "minimum": 0 }, "total_capacity": { "type": "integer", "description": "Sum of `max_concurrency` across all `active` + `draining` workers.", "minimum": 0 }, "total_load": { "type": "integer", "description": "Total tasks currently in flight across all workers.", "minimum": 0 } } }, "WorkflowEventResponse": { "type": "object", "description": "Workflow event response", "required": [ "id", "workflow_id", "sequence_num", "event_type", "event_data", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339)." }, "event_data": {}, "event_type": { "type": "string" }, "id": { "type": "integer", "format": "int64", "description": "Monotonically-assigned internal event identifier." }, "sequence_num": { "type": "integer", "format": "int32" }, "workflow_id": { "type": "string", "format": "uuid", "description": "Durable workflow's identifier." } } }, "WorkflowEventsListResponse": { "type": "object", "description": "Workflow events list response", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEventResponse" }, "description": "Page of items returned by this query." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages.", "minimum": 0 } } }, "WorkflowResponse": { "type": "object", "description": "Workflow response", "required": [ "id", "workflow_type", "status", "input", "created_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource completed, if any (RFC 3339).", "example": "2026-05-27T15:24:42Z" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this resource was created (RFC 3339).", "example": "2026-05-27T15:24:00Z" }, "error": { "type": "object", "description": "Human-readable error message, populated when this resource is in a failed state." }, "id": { "type": "string", "format": "uuid", "description": "UUID of the workflow.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "input": { "type": "object", "description": "Initial input the workflow was started with. Shape varies by `workflow_type`." }, "result": { "type": "object", "description": "Terminal result, populated when the workflow has completed successfully." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when this resource started, if any (RFC 3339).", "example": "2026-05-27T15:24:01Z" }, "status": { "type": "string", "description": "Current lifecycle status.", "example": "running" }, "workflow_type": { "type": "string", "description": "Workflow type identifier registered with the durable executor.", "example": "session_agent_loop" } } }, "WorkflowsListResponse": { "type": "object", "description": "Workflows list response", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowResponse" }, "description": "Page of items returned by this query." }, "total": { "type": "integer", "description": "Total number of items matching the query, across all pages.", "minimum": 0 } } }, "Workspace": { "type": "object", "required": [ "id", "name", "status", "created_at", "updated_at" ], "properties": { "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ], "example": "Shared workspace for the Q4 research project" }, "id": { "type": "string", "example": "wsp_01933b5a000070008000000000000001" }, "name": { "type": "string", "example": "team-research" }, "status": { "type": "string", "example": "active" }, "updated_at": { "type": "string", "format": "date-time" } } }, "agentId": { "type": "string", "description": "Prefixed identifier with 'agent' prefix", "example": "agent_01933b5a000070008000000000000001", "pattern": "^agent_[0-9a-f]{32}$" }, "agentverId": { "type": "string", "description": "Prefixed identifier with 'agentver' prefix", "example": "agentver_01933b5a000070008000000000000001", "pattern": "^agentver_[0-9a-f]{32}$" }, "eventId": { "type": "string", "description": "Prefixed identifier with 'event' prefix", "example": "event_01933b5a000070008000000000000001", "pattern": "^event_[0-9a-f]{32}$" }, "harnessId": { "type": "string", "description": "Prefixed identifier with 'harness' prefix", "example": "harness_01933b5a000070008000000000000001", "pattern": "^harness_[0-9a-f]{32}$" }, "payacctId": { "type": "string", "description": "Prefixed identifier with 'payacct' prefix", "example": "payacct_01933b5a000070008000000000000001", "pattern": "^payacct_[0-9a-f]{32}$" }, "payattId": { "type": "string", "description": "Prefixed identifier with 'payatt' prefix", "example": "payatt_01933b5a000070008000000000000001", "pattern": "^payatt_[0-9a-f]{32}$" }, "paypolId": { "type": "string", "description": "Prefixed identifier with 'paypol' prefix", "example": "paypol_01933b5a000070008000000000000001", "pattern": "^paypol_[0-9a-f]{32}$" }, "sessionId": { "type": "string", "description": "Prefixed identifier with 'session' prefix", "example": "session_01933b5a000070008000000000000001", "pattern": "^session_[0-9a-f]{32}$" } } }, "tags": [ { "name": "agents", "description": "Agent management endpoints" }, { "name": "sessions", "description": "Session management endpoints" }, { "name": "messages", "description": "Message management endpoints" }, { "name": "voice", "description": "Realtime voice session endpoints" }, { "name": "events", "description": "Event streaming endpoints (SSE)" }, { "name": "providers", "description": "LLM Provider management endpoints" }, { "name": "models", "description": "LLM Model management endpoints" }, { "name": "capabilities", "description": "Capability management endpoints" }, { "name": "users", "description": "User management endpoints" }, { "name": "filesystem", "description": "Session virtual filesystem endpoints" }, { "name": "session-resources", "description": "Session leased-resource visibility endpoints" }, { "name": "session-sandbox", "description": "Managed session sandbox lifecycle endpoints" }, { "name": "mcp-servers", "description": "MCP Server management endpoints" }, { "name": "durable-schedules", "description": "Durable scheduled tasks management endpoints" }, { "name": "organizations", "description": "Organization management endpoints" }, { "name": "memory", "description": "Org-scoped named Memory management endpoints" }, { "name": "knowledge_bases", "description": "Knowledge base and entry management endpoints" }, { "name": "knowledge_indexes", "description": "Knowledge index and document management endpoints" }, { "name": "images", "description": "Image upload and management endpoints" }, { "name": "session-databases", "description": "Session-scoped SQL database endpoints" }, { "name": "session-storage", "description": "Session key-value storage endpoints" }, { "name": "harnesses", "description": "Harness management endpoints" }, { "name": "agent-triggers", "description": "Agent-owned schedule trigger endpoints" }, { "name": "skills", "description": "Skills registry endpoints" }, { "name": "payments", "description": "Machine payment wallet, policy, and attempt endpoints" }, { "name": "reporting", "description": "Org-scoped semantic reporting endpoints" }, { "name": "task-webhooks", "description": "Outbound HTTP webhooks fired on terminal task transitions" } ] }