{ "openapi": "3.1.0", "info": { "title": "Cruq AI API", "version": "1.0.0", "description": "The public REST API for Cruq AI - build, run, and own AI agents. Create agents, run them, and manage prompts, tools, guardrails, memory, knowledge bases, evals, schedules, providers and API keys. All endpoints are tenant-scoped and authenticated with a Bearer API key (cruq_sk_...). Timestamps are ISO 8601 strings; cost_usd values are exact-decimal strings.", "contact": { "name": "Cruq AI", "email": "hello@cruq.ai", "url": "https://www.cruq.ai/contact" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.cruq.ai", "description": "Production" } ], "externalDocs": { "description": "Cruq AI documentation", "url": "https://docs.cruq.ai" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Agents", "description": "Create, version, and run agents" }, { "name": "Runs", "description": "Inspect agent runs and their tool-call traces" }, { "name": "Threads", "description": "Conversation threads grouped by agent" }, { "name": "Tools", "description": "The tenant tool catalog" }, { "name": "Prompts", "description": "Reusable prompt templates" }, { "name": "Guardrails", "description": "Input/output guardrails" }, { "name": "Memory", "description": "Long-term agent memory with semantic recall" }, { "name": "Knowledge", "description": "Knowledge bases and document ingestion" }, { "name": "Evals", "description": "Eval suites, cases, and model-comparison experiments" }, { "name": "Providers" }, { "name": "Schedules" }, { "name": "API keys" }, { "name": "Deployments", "description": "Hosted agent apps on cruq.app" }, { "name": "Skills", "description": "Skills and subagents" }, { "name": "Channels", "description": "Channels and integrations" }, { "name": "Members", "description": "Workspace members and invites" }, { "name": "Voice", "description": "Voice call history" }, { "name": "Browser", "description": "Saved sign-ins and portal logins for the browser tool." } ], "paths": { "/v1/agents": { "get": { "operationId": "listAgents", "summary": "List agents", "tags": [ "Agents" ], "responses": { "200": { "description": "The tenant's agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createAgent", "summary": "Create an agent (or return the existing one by name)", "tags": [ "Agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpsert" } } } }, "200": { "description": "Already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpsert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agents/{id}": { "parameters": [ { "$ref": "#/components/parameters/AgentRef" } ], "delete": { "operationId": "deleteAgent", "summary": "Delete an agent by id or name", "tags": [ "Agents" ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateAgent", "summary": "Rename or re-describe an agent", "tags": [ "Agents" ], "description": "Management keys only. The name is the CLI ref, so a rename changes it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Agent name already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agents/{id}/versions": { "parameters": [ { "$ref": "#/components/parameters/AgentRef" } ], "get": { "operationId": "getAgentGraph", "summary": "Get the agent's current graph (published, else latest draft)", "tags": [ "Agents" ], "responses": { "200": { "description": "Current version and graph", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "version": { "type": "integer" }, "version_id": { "type": "string" }, "status": { "type": "string" }, "published": { "type": "boolean" }, "graph": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "createAgentVersion", "summary": "Create a new agent version from a graph (publishes by default)", "tags": [ "Agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "graph" ], "properties": { "graph": { "type": "object" }, "publish": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Version created", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{id}/runs": { "parameters": [ { "$ref": "#/components/parameters/AgentRef" } ], "post": { "operationId": "runAgent", "summary": "Run the agent's published version (Server-Sent Events stream)", "description": "Returns a text/event-stream of run events, not JSON. Rate limited to 60 requests / 60s per API key.", "tags": [ "Agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string" }, "thread_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "SSE stream of run events", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Agent has no published version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/runs": { "get": { "operationId": "listRuns", "summary": "List recent runs", "tags": [ "Runs" ], "parameters": [ { "name": "agent", "in": "query", "schema": { "type": "string" }, "description": "Filter by agent id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Recent runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/runs/{runId}": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getRun", "summary": "Get a run with its tool-call step trace", "tags": [ "Runs" ], "responses": { "200": { "description": "Run and steps", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/Run" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/Step" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/threads": { "get": { "operationId": "listThreads", "summary": "List conversation threads for an agent", "tags": [ "Threads" ], "parameters": [ { "name": "agent", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent id or name" } ], "responses": { "200": { "description": "Threads newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "type": "object", "properties": { "thread_id": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "run_count": { "type": "integer" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/threads/{threadId}": { "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getThread", "summary": "Get all turns in a thread", "tags": [ "Threads" ], "parameters": [ { "name": "agent", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent id or name" } ], "responses": { "200": { "description": "Thread turns oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "thread_id": { "type": "string" }, "turns": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tools": { "get": { "operationId": "listTools", "summary": "List the tenant tool catalog", "tags": [ "Tools" ], "responses": { "200": { "description": "Tools", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createTool", "summary": "Create a tool (or return the existing one by name)", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "builtin": { "type": "string" }, "http": { "type": "object" }, "mcp": { "type": "object" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolUpsert" } } } }, "200": { "description": "Already existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolUpsert" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/prompts": { "get": { "operationId": "listPrompts", "summary": "List prompt templates", "tags": [ "Prompts" ], "responses": { "200": { "description": "Prompts", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompts": { "type": "array", "items": { "$ref": "#/components/schemas/Prompt" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "upsertPrompt", "summary": "Create a prompt, or update and bump its version (by name)", "tags": [ "Prompts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "template" ], "properties": { "name": { "type": "string" }, "template": { "type": "string" }, "description": { "type": "string" }, "model": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "integer" } } }, "created": { "type": "boolean" } } } } } }, "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/prompts/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deletePrompt", "summary": "Delete a prompt by name", "tags": [ "Prompts" ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updatePrompt", "summary": "Rename or edit a prompt", "tags": [ "Prompts" ], "description": "Management keys only. Editing template, description or model bumps the version; a rename alone does not.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "template": { "type": "string" }, "model": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Prompt name already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/guardrails": { "get": { "operationId": "listGuardrails", "summary": "List guardrails", "tags": [ "Guardrails" ], "responses": { "200": { "description": "Guardrails", "content": { "application/json": { "schema": { "type": "object", "properties": { "guardrails": { "type": "array", "items": { "$ref": "#/components/schemas/Guardrail" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "upsertGuardrail", "summary": "Create or update a guardrail (by name)", "tags": [ "Guardrails" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "pii", "regex", "keyword", "max_length", "json_schema", "semantic" ] }, "target": { "type": "string", "enum": [ "input", "output", "both" ], "default": "both" }, "action": { "type": "string", "enum": [ "block", "redact", "warn" ], "default": "block" }, "enabled": { "type": "boolean", "default": true }, "description": { "type": "string" }, "config": { "type": "object", "description": "Per kind: regex {pattern}; keyword {keywords[]}; max_length {maxChars}; semantic {questions: {: {instructions, threshold?} | string}, threshold? (default 0.7), context?, failClosed?}. Semantic questions are statements answered by the decision model; at or above the threshold the guardrail trips." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/guardrails/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteGuardrail", "summary": "Delete a guardrail by name", "tags": [ "Guardrails" ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "setGuardrailEnabled", "summary": "Enable or disable a guardrail by name", "tags": [ "Guardrails" ], "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } } } } } }, "/v1/memory": { "get": { "operationId": "listMemories", "summary": "List stored memories", "tags": [ "Memory" ], "responses": { "200": { "description": "Memories", "content": { "application/json": { "schema": { "type": "object", "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/Memory" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createMemory", "summary": "Store (embed) a memory", "tags": [ "Memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } } } } } }, "responses": { "201": { "description": "Stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "memory": { "type": "object", "properties": { "id": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/v1/memory/search": { "post": { "operationId": "searchMemory", "summary": "Semantic recall over memories", "tags": [ "Memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "k": { "type": "integer", "default": 5 } } } } } }, "responses": { "200": { "description": "Hits", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "similarity": { "type": "number" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/v1/memory/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteMemory", "summary": "Delete a memory by id (idempotent)", "tags": [ "Memory" ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "operationId": "updateMemory", "summary": "Rewrite a memory", "tags": [ "Memory" ], "description": "Management keys only. The new content is re-embedded.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "memory": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/knowledge": { "get": { "operationId": "listKnowledgeBases", "summary": "List knowledge bases", "tags": [ "Knowledge" ], "responses": { "200": { "description": "Knowledge bases", "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledge_bases": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createKnowledgeBase", "summary": "Create a knowledge base (or return the existing one by name)", "tags": [ "Knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "200": { "description": "Already existed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/knowledge/search": { "post": { "operationId": "searchKnowledge", "summary": "Cosine search over embedded chunks, optionally scoped to one base", "tags": [ "Knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "kb": { "type": "string", "description": "Knowledge base name" }, "k": { "type": "integer", "default": 5 } } } } } }, "responses": { "200": { "description": "Hits", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string" }, "document_id": { "type": "string" }, "similarity": { "type": "number" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/v1/knowledge/{kb}": { "parameters": [ { "name": "kb", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge base name" } ], "delete": { "operationId": "deleteKnowledgeBase", "summary": "Delete a knowledge base by name (cascades documents)", "tags": [ "Knowledge" ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateKnowledgeBase", "summary": "Rename or re-describe a knowledge base", "tags": [ "Knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledge_base": { "$ref": "#/components/schemas/KnowledgeBase" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Knowledge base name already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge/{kb}/documents": { "parameters": [ { "name": "kb", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge base name" } ], "get": { "operationId": "listKnowledgeDocuments", "summary": "List documents in a knowledge base", "tags": [ "Knowledge" ], "responses": { "200": { "description": "Documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "ingestKnowledgeDocument", "summary": "Ingest a document (chunk + embed); accepts JSON or multipart", "description": "Returns 202 - the document is queued for a background worker. Poll the document for its status.", "tags": [ "Knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "title": { "type": "string" }, "content": { "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "title": { "type": "string" }, "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/v1/evals/suites": { "get": { "operationId": "listEvalSuites", "summary": "List eval suites", "tags": [ "Evals" ], "parameters": [ { "name": "agent", "in": "query", "schema": { "type": "string" }, "description": "Agent id or name for an agent-scoped listing" } ], "responses": { "200": { "description": "Suites", "content": { "application/json": { "schema": { "type": "object", "properties": { "suites": { "type": "array", "items": { "$ref": "#/components/schemas/Suite" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "createEvalSuite", "summary": "Create an eval suite", "tags": [ "Evals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "agent": { "type": "string" }, "workspace_wide": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/evals/suites/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Suite id or name" } ], "get": { "operationId": "getEvalSuite", "summary": "Get a suite with its cases", "tags": [ "Evals" ], "responses": { "200": { "description": "Suite and cases", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "renameEvalSuite", "summary": "Rename a suite", "tags": [ "Evals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Renamed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "deleteEvalSuite", "summary": "Delete a suite and its cases", "tags": [ "Evals" ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/evals/suites/{ref}/cases": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Suite id or name" } ], "get": { "operationId": "listEvalCases", "summary": "List a suite's cases", "tags": [ "Evals" ], "responses": { "200": { "description": "Cases", "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "array", "items": { "$ref": "#/components/schemas/EvalCase" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createEvalCase", "summary": "Add a case to a suite", "tags": [ "Evals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "input", "scorers" ], "properties": { "name": { "type": "string" }, "input": { "type": "string" }, "scorers": { "type": "array", "items": { "type": "object" } }, "weight": { "type": "number", "default": 1 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/evals/cases/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteEvalCase", "summary": "Remove a single case", "tags": [ "Evals" ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "operationId": "updateEvalCase", "summary": "Edit a case", "tags": [ "Evals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "input": { "type": "string" }, "scorers": { "type": "array", "items": { "type": "object" } }, "weight": { "type": "number" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/evals/experiments": { "get": { "operationId": "listEvalExperiments", "summary": "List experiments", "tags": [ "Evals" ], "parameters": [ { "name": "agent", "in": "query", "schema": { "type": "string" }, "description": "Agent id or name" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Experiments", "content": { "application/json": { "schema": { "type": "object", "properties": { "experiments": { "type": "array", "items": { "$ref": "#/components/schemas/Experiment" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "createEvalExperiment", "summary": "Start a model-comparison experiment", "tags": [ "Evals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent", "suite", "name", "variants" ], "properties": { "agent": { "type": "string" }, "suite": { "type": "string" }, "name": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object" } }, "judge_model": { "type": "string" }, "budget_usd": { "type": "number" } } } } } }, "responses": { "201": { "description": "Started", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/evals/experiments/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getEvalExperiment", "summary": "Get an experiment summary and leaderboard", "tags": [ "Evals" ], "parameters": [ { "name": "results", "in": "query", "schema": { "type": "boolean" }, "description": "Include per-cell results" } ], "responses": { "200": { "description": "Experiment", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "renameEvalExperiment", "summary": "Rename an experiment", "tags": [ "Evals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Renamed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "cancelEvalExperiment", "summary": "Cancel an experiment", "tags": [ "Evals" ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/knowledge/{kb}/graph": { "parameters": [ { "name": "kb", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge base name" } ], "get": { "operationId": "getKnowledgeGraph", "summary": "Knowledge graph of a base (entities and relationships)", "tags": [ "Knowledge" ], "responses": { "200": { "description": "Graph", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "nodes": { "type": "array", "items": { "type": "object" } }, "edges": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "parameters": [ { "name": "entity", "in": "query", "schema": { "type": "string" }, "description": "Center the subgraph on this entity" }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ] } }, "/v1/providers": { "get": { "operationId": "listProviders", "summary": "List provider connections (keys are never returned)", "tags": [ "Providers" ], "responses": { "200": { "description": "Connections", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderConnection" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "description": "Management keys only." }, "post": { "operationId": "connectProvider", "summary": "Connect a model provider", "tags": [ "Providers" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "label": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "description": "Management keys only. `typesafe` is a decision provider for semantic guardrails, not a chat provider.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "label", "api_key" ], "properties": { "provider": { "type": "string", "enum": [ "openrouter", "openai", "openai_compatible", "typesafe" ] }, "label": { "type": "string" }, "api_key": { "type": "string", "description": "Encrypted at rest, never returned" }, "base_url": { "type": "string", "description": "Required for openai_compatible" } } } } } } } }, "/v1/providers/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id or label" } ], "delete": { "operationId": "deleteProvider", "summary": "Remove a provider connection", "tags": [ "Providers" ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/runs/{runId}/answer": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "answerRun", "summary": "Answer the question a paused run is waiting on", "tags": [ "Runs" ], "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Run is not paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "description": "The continuation is queued to a worker. Poll GET /v1/runs/{runId} for the outcome.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "answer" ], "properties": { "answer": { "type": "string" }, "interrupt_id": { "type": "string", "description": "Guard against answering a question that is no longer pending" } } } } } } } }, "/v1/schedules": { "get": { "operationId": "listSchedules", "summary": "List schedules", "tags": [ "Schedules" ], "responses": { "200": { "description": "Schedules", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "parameters": [ { "name": "agent", "in": "query", "schema": { "type": "string" }, "description": "Agent id or name; omit for all" } ] }, "post": { "operationId": "createSchedule", "summary": "Create a schedule", "tags": [ "Schedules" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/Schedule" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Plan limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "description": "Management keys only. hourly ignores hour and weekday; daily needs hour; weekly needs hour and weekday.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent", "name", "input", "frequency" ], "properties": { "agent": { "type": "string", "description": "Agent id or name" }, "name": { "type": "string" }, "input": { "type": "string", "description": "The prompt sent to the agent on each run" }, "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6 }, "timezone": { "type": "string", "default": "UTC" }, "enabled": { "type": "boolean" } } } } } } } }, "/v1/schedules/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getSchedule", "summary": "Get a schedule", "tags": [ "Schedules" ], "responses": { "200": { "description": "Schedule", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/Schedule" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "operationId": "updateSchedule", "summary": "Edit a schedule (fields, or enable/disable)", "tags": [ "Schedules" ], "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/Schedule" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Plan limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "input": { "type": "string", "description": "The prompt sent to the agent on each run" }, "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6 }, "timezone": { "type": "string", "default": "UTC" }, "enabled": { "type": "boolean" } } } } } } }, "delete": { "operationId": "deleteSchedule", "summary": "Delete a schedule", "tags": [ "Schedules" ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "tags": [ "API keys" ], "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "description": "Management keys only.", "parameters": [ { "name": "usage", "in": "query", "schema": { "type": "boolean" }, "description": "Include current-period spend on runtime keys" } ] }, "post": { "operationId": "createApiKey", "summary": "Create an API key (the full key is returned once)", "tags": [ "API keys" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "object", "properties": { "id": { "type": "string" }, "prefix": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" } } }, "key": { "type": "string", "description": "The full key. Not stored; cannot be retrieved again." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "description": "Management keys only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "runtime", "management" ], "default": "runtime" }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 3650 }, "spend_limit_usd": { "type": "number", "description": "Runtime keys only" }, "spend_reset_period": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] } } } } } } } }, "/v1/api-keys/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "tags": [ "API keys" ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/deployments": { "get": { "operationId": "listDeployments", "summary": "List hosted apps", "tags": [ "Deployments" ], "responses": { "200": { "description": "Deployments", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/Deployment" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createDeployment", "summary": "Deploy a published agent as a hosted app", "tags": [ "Deployments" ], "description": "Management keys only. The agent must have a published version. Without a subdomain a random one is assigned. Created as a draft unless status is given.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent" ], "properties": { "agent": { "type": "string", "description": "Agent id or name" }, "subdomain": { "type": "string", "description": "5 to 63 chars, lowercase letters, digits and hyphens" }, "branding": { "$ref": "#/components/schemas/DeploymentBranding" }, "auth_mode": { "type": "string", "enum": [ "public", "require_login" ] }, "status": { "type": "string", "enum": [ "draft", "live", "disabled" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "$ref": "#/components/schemas/Deployment" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Subdomain taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/deployments/availability": { "get": { "operationId": "checkSubdomain", "summary": "Is a subdomain valid and free?", "tags": [ "Deployments" ], "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Availability", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "subdomain": { "type": "string" }, "reason": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/deployments/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment id or subdomain" } ], "get": { "operationId": "getDeployment", "summary": "Get a hosted app", "tags": [ "Deployments" ], "responses": { "200": { "description": "Deployment", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "$ref": "#/components/schemas/Deployment" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateDeployment", "summary": "Update subdomain, branding, login mode or status", "tags": [ "Deployments" ], "description": "branding replaces the whole object when given.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subdomain": { "type": "string", "description": "5 to 63 chars, lowercase letters, digits and hyphens" }, "branding": { "$ref": "#/components/schemas/DeploymentBranding" }, "auth_mode": { "type": "string", "enum": [ "public", "require_login" ] }, "status": { "type": "string", "enum": [ "draft", "live", "disabled" ] } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "$ref": "#/components/schemas/Deployment" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Subdomain taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDeployment", "summary": "Delete a hosted app", "tags": [ "Deployments" ], "description": "Releases the subdomain, the custom domain and stored images.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/deployments/{ref}/users": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment id or subdomain" } ], "get": { "operationId": "listDeploymentUsers", "summary": "End-users of the app", "tags": [ "Deployments" ], "responses": { "200": { "description": "Users", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentUser" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/deployments/{ref}/users/{uid}/block": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment id or subdomain" }, { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "End-user id" } ], "post": { "operationId": "blockDeploymentUser", "summary": "Block an end-user", "tags": [ "Deployments" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "blocked": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "unblockDeploymentUser", "summary": "Lift a block", "tags": [ "Deployments" ], "responses": { "200": { "description": "Unblocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "blocked": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/deployments/{ref}/analytics": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment id or subdomain" } ], "get": { "operationId": "getDeploymentAnalytics", "summary": "Traffic and engagement", "tags": [ "Deployments" ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 7, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentAnalytics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/deployments/{ref}/channels": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment id or subdomain" } ], "get": { "operationId": "listDeploymentChannels", "summary": "Bot channels connected to the app", "tags": [ "Deployments" ], "responses": { "200": { "description": "Channels", "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "enabled": { "type": "boolean" }, "status": { "type": [ "string", "null" ] } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/deployments/{ref}/assets": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment id or subdomain" } ], "post": { "operationId": "uploadDeploymentImage", "summary": "Upload a logo or hero image", "tags": [ "Deployments" ], "description": "PNG, JPEG, WebP or GIF up to 4 MB. Points the matching branding field at the stored image.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "kind", "file" ], "properties": { "kind": { "type": "string", "enum": [ "logo", "hero" ] }, "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "$ref": "#/components/schemas/Deployment" }, "url": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Uploads not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/deployments/{ref}/domain": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment id or subdomain" } ], "get": { "operationId": "getDeploymentDomain", "summary": "Custom domain and its DNS status", "tags": [ "Deployments" ], "responses": { "200": { "description": "Domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentDomain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setDeploymentDomain", "summary": "Attach a custom domain", "tags": [ "Deployments" ], "description": "Adds the hostname to the apps project. Point a CNAME at cname_target, then verify.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" } } } } } }, "responses": { "200": { "description": "Domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Domain in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Custom domains not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "removeDeploymentDomain", "summary": "Detach the custom domain", "tags": [ "Deployments" ], "responses": { "200": { "description": "Domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentDomain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/deployments/{ref}/domain/verify": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment id or subdomain" } ], "post": { "operationId": "verifyDeploymentDomain", "summary": "Re-check DNS for the custom domain", "tags": [ "Deployments" ], "responses": { "200": { "description": "Domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentDomain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Runtime key (management scope required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/skills": { "get": { "operationId": "listSkills", "summary": "List skills", "tags": [ "Skills" ], "responses": { "200": { "description": "Skills", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "upsertSkill", "summary": "Create or update a skill by name", "tags": [ "Skills" ], "description": "Management keys only. name: lowercase letters, digits and dashes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "body": { "type": "string", "description": "The instructions" }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" } }, "required": [ "name", "body" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "created": { "type": "boolean" } } } } } }, "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "object" }, "created": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/skills/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill name or id" } ], "get": { "operationId": "getSkill", "summary": "Get a skill", "tags": [ "Skills" ], "responses": { "200": { "description": "Skill", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "$ref": "#/components/schemas/Skill" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateSkill", "summary": "Rename, edit or toggle a skill", "tags": [ "Skills" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "$ref": "#/components/schemas/Skill" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Skill name already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteSkill", "summary": "Delete a skill", "tags": [ "Skills" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/subagents": { "get": { "operationId": "listSubagents", "summary": "Agents exposed as tools", "tags": [ "Skills" ], "responses": { "200": { "description": "Subagents", "content": { "application/json": { "schema": { "type": "object", "properties": { "subagents": { "type": "array", "items": { "$ref": "#/components/schemas/Subagent" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "createSubagent", "summary": "Expose an agent as a subagent tool", "tags": [ "Skills" ], "description": "Management keys only. Idempotent per agent name. Attach the returned tool id to a parent node's toolRefs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string", "description": "Agent id or name" } }, "required": [ "agent" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "subagent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "created": { "type": "boolean" } } } } } }, "200": { "description": "Already existed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/subagents/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tool id or the agent's name" } ], "delete": { "operationId": "deleteSubagent", "summary": "Remove a subagent tool", "tags": [ "Skills" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/knowledge/{kb}/documents/{doc}": { "parameters": [ { "name": "kb", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge base name or id" }, { "name": "doc", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document id" } ], "patch": { "operationId": "renameDocument", "summary": "Retitle a document", "tags": [ "Knowledge" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteDocument", "summary": "Delete a document and its chunks", "tags": [ "Knowledge" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/channels": { "get": { "operationId": "listChannels", "summary": "List channels", "tags": [ "Channels" ], "parameters": [ { "name": "agent", "in": "query", "schema": { "type": "string" } }, { "name": "deployment", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channels", "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "connectChannel", "summary": "Connect a Slack channel or Telegram bot", "tags": [ "Channels" ], "description": "Management keys only. Tokens are encrypted and never returned. A Telegram webhook is registered; a rejection comes back as `warning`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string", "description": "Agent id or name" }, "deployment": { "type": "string", "description": "Hosted app id or subdomain; the channel becomes its bot" }, "kind": { "type": "string", "enum": [ "slack", "telegram" ] }, "slack_channel_id": { "type": "string" }, "signing_secret": { "type": "string" }, "slack_bot_token": { "type": "string" }, "telegram_bot_token": { "type": "string" } }, "required": [ "kind" ] } } } }, "responses": { "201": { "description": "Connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/Channel" }, "warning": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/channels/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel id" } ], "patch": { "operationId": "setChannelEnabled", "summary": "Enable or disable a channel", "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/Channel" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteChannel", "summary": "Remove a channel", "tags": [ "Channels" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/integrations": { "get": { "operationId": "listIntegrations", "summary": "Connections and the connector catalog", "tags": [ "Channels" ], "responses": { "200": { "description": "Integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } }, "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/Connector" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "connectIntegration", "summary": "Connect an API-key connector", "tags": [ "Channels" ], "description": "Management keys only. The secret is probed against the service before it is saved. OAuth connectors connect from the dashboard.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connector": { "type": "string" }, "secret": { "type": "string" }, "label": { "type": "string" } }, "required": [ "connector" ] } } } }, "responses": { "201": { "description": "Connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/Connection" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "description": "Could not save", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/integrations/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id, label or connector slug" } ], "delete": { "operationId": "disconnectIntegration", "summary": "Remove a connection", "tags": [ "Channels" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/members": { "get": { "operationId": "listMembers", "summary": "Members and pending invites", "tags": [ "Members" ], "responses": { "200": { "description": "Members", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "invites": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Not allowed for this key or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/members/invites": { "post": { "operationId": "inviteMember", "summary": "Invite someone by email", "tags": [ "Members" ], "description": "Management keys only; a key acts as an admin and cannot invite an owner. Sends the email and returns the link.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string", "enum": [ "member", "admin", "owner" ], "default": "member" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Invited", "content": { "application/json": { "schema": { "type": "object", "properties": { "invite": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "role": { "type": "string" }, "link": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] } } }, "warning": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Not allowed for this key or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/members/invites/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invite id or email" } ], "delete": { "operationId": "revokeInvite", "summary": "Revoke a pending invite", "tags": [ "Members" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Not allowed for this key or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/members/{user}": { "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id or email" } ], "patch": { "operationId": "setMemberRole", "summary": "Change a member's role", "tags": [ "Members" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "member", "admin", "owner" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "$ref": "#/components/schemas/Member" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Not allowed for this key or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "removeMember", "summary": "Remove a member", "tags": [ "Members" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "403": { "description": "Not allowed for this key or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/voice-calls": { "get": { "operationId": "listVoiceCalls", "summary": "Recent voice calls", "tags": [ "Voice" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Calls", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceCall" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/voice-calls/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call id" } ], "get": { "operationId": "getVoiceCall", "summary": "A call with its transcript", "tags": [ "Voice" ], "responses": { "200": { "description": "Call", "content": { "application/json": { "schema": { "type": "object", "properties": { "call": { "$ref": "#/components/schemas/VoiceCall" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/voice-calls/{id}/recording": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call id" } ], "get": { "operationId": "getVoiceCallRecording", "summary": "The call recording", "tags": [ "Voice" ], "responses": { "200": { "description": "WAV audio", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "description": "Recording storage not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/runs/{runId}/screenshots": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listRunScreenshots", "summary": "List the screenshots the browser tool kept for a run", "tags": [ "Runs" ], "responses": { "200": { "description": "Screenshot metadata, one per browser action", "content": { "application/json": { "schema": { "type": "object", "properties": { "screenshots": { "type": "array", "items": { "$ref": "#/components/schemas/Screenshot" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runs/{runId}/screenshots/{seq}": { "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "get": { "operationId": "getRunScreenshot", "summary": "One screenshot as PNG", "tags": [ "Runs" ], "responses": { "200": { "description": "The image", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tools/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "updateTool", "summary": "Edit a tool's settings in place (management key)", "tags": [ "Tools" ], "description": "Replaces the given blocks of the tool's config. For the browser builtin: {\"builtin\": {\"key\": \"browser\", \"browser\": {\"allowedDomains\": [\"portal.example.com\"], \"approvals\": \"consequential\", \"maxActions\": 40, \"maxMinutes\": 10}}}.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "builtin": { "type": "object" }, "http": { "type": "object" }, "mcp": { "type": "object" } } } } } }, "responses": { "200": { "description": "The updated tool", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/browser/profiles": { "get": { "operationId": "listBrowserProfiles", "summary": "List saved browser sign-ins (management key)", "tags": [ "Browser" ], "description": "Cookies are never returned; `signed_in` says whether the profile holds a session.", "responses": { "200": { "description": "Profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserProfile" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createBrowserProfile", "summary": "Create an empty browser profile (management key)", "tags": [ "Browser" ], "description": "A profile starts empty: the next run that signs in writes its cookies back, so there is nothing to supply here beyond a name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Invalid profile" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/browser/profiles/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The profile or credential's name or id." } ], "delete": { "operationId": "deleteBrowserProfile", "summary": "Delete a browser profile and its sign-in", "tags": [ "Browser" ], "responses": { "200": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/browser/profiles/{ref}/clear": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The profile or credential's name or id." } ], "post": { "operationId": "clearBrowserProfile", "summary": "Forget a profile's sign-in but keep the profile", "tags": [ "Browser" ], "responses": { "200": { "description": "Cleared" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/browser/credentials": { "get": { "operationId": "listBrowserCredentials", "summary": "List stored portal logins (management key)", "tags": [ "Browser" ], "description": "Passwords are never returned. A login is only ever typed on the domain it was stored for.", "responses": { "200": { "description": "Credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserCredential" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createBrowserCredential", "summary": "Store a portal login (management key)", "tags": [ "Browser" ], "description": "The password is encrypted at rest and read only by the runtime, at the moment it types it into a form. The model names the credential and never sees its value.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "domain", "username", "password" ], "properties": { "name": { "type": "string" }, "domain": { "type": "string", "example": "portal.example.com" }, "username": { "type": "string" }, "password": { "type": "string", "format": "password" } } } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Invalid credential" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/browser/credentials/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The profile or credential's name or id." } ], "delete": { "operationId": "deleteBrowserCredential", "summary": "Delete a stored login", "tags": [ "Browser" ], "responses": { "200": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cruq_sk_...", "description": "A tenant API key. Send as: Authorization: Bearer cruq_sk_..." } }, "parameters": { "AgentRef": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent id or name" } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Conflict (e.g. ambiguous name or name already taken)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UpstreamError": { "description": "Upstream failure (embedding/search/enqueue)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Deleted": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "oneOf": [ { "type": "boolean" }, { "type": "string" } ] } } } } } } }, "schemas": { "Error": { "type": "object", "description": "Standard error envelope. Some validation errors add issues[] or suite_ids[].", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "hint": { "type": "string" }, "issues": { "type": "array", "items": { "type": "string" } } } }, "Agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "published_version_id": { "type": [ "string", "null" ] } } }, "AgentUpsert": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "created": { "type": "boolean" } } }, "Run": { "type": "object", "properties": { "id": { "type": "string" }, "agent_id": { "type": "string" }, "agent_version_id": { "type": "string" }, "thread_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "input": { "type": "string" }, "output": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "model": { "type": [ "string", "null" ] }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": [ "integer", "null" ] }, "completion_tokens": { "type": [ "integer", "null" ] }, "total_tokens": { "type": [ "integer", "null" ] }, "cost_usd": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "browser_ms": { "type": "integer", "nullable": true, "description": "Time a hosted browser session was open for this run, in milliseconds; null when the browser tool was not used." } } }, "interrupt": { "type": [ "object", "null" ], "description": "The question a paused run is waiting on (status = paused)", "properties": { "id": { "type": "string" }, "value": {}, "node_id": { "type": [ "string", "null" ] }, "asked_at": { "type": "string", "format": "date-time" } } } } }, "Step": { "type": "object", "properties": { "seq": { "type": "integer" }, "type": { "type": "string" }, "node_id": { "type": [ "string", "null" ] }, "tool_name": { "type": [ "string", "null" ] }, "tool_call_id": { "type": [ "string", "null" ] }, "args": {}, "result": {}, "created_at": { "type": "string", "format": "date-time" } } }, "Tool": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "config": { "type": "object" } } }, "ToolUpsert": { "type": "object", "properties": { "tool": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "created": { "type": "boolean" } } }, "Prompt": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "template": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "model": { "type": [ "string", "null" ] }, "version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Guardrail": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "target": { "type": "string" }, "action": { "type": "string" }, "config": { "type": "object" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Memory": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "KnowledgeBase": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "embedding_model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "Document": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "chunk_count": { "type": "integer" }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Suite": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "agent_id": { "type": [ "string", "null" ] }, "agent_name": { "type": [ "string", "null" ] }, "case_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "EvalCase": { "type": "object", "properties": { "id": { "type": "string" }, "suite_id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "string" }, "scorers": { "type": "array", "items": { "type": "object" } }, "weight": { "type": "number" }, "order_index": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "Experiment": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "agent_id": { "type": "string" }, "agent_name": { "type": "string" }, "agent_version_id": { "type": "string" }, "suite_id": { "type": "string" }, "suite_name": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object" } }, "judge_model": { "type": [ "string", "null" ] }, "budget_usd": { "type": [ "number", "null" ] }, "note": { "type": [ "string", "null" ] }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" } } }, "ProviderConnection": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string", "enum": [ "openrouter", "openai", "openai_compatible", "typesafe" ] }, "label": { "type": "string" }, "base_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Schedule": { "type": "object", "properties": { "id": { "type": "string" }, "agent_id": { "type": "string" }, "name": { "type": "string" }, "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] }, "hour": { "type": [ "integer", "null" ] }, "minute": { "type": "integer" }, "weekday": { "type": [ "integer", "null" ], "description": "0 = Monday .. 6 = Sunday" }, "timezone": { "type": "string" }, "input": { "type": "string" }, "enabled": { "type": "boolean" }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "kind": { "type": "string", "enum": [ "runtime", "management" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "spend_limit_usd": { "type": [ "string", "null" ] }, "spend_reset_period": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", null ] }, "created_at": { "type": "string", "format": "date-time" }, "usage": { "type": "object", "description": "Present with ?usage=true on active runtime keys", "properties": { "used_usd": { "type": "number" }, "limit_usd": { "type": [ "number", "null" ] }, "reset_period": { "type": [ "string", "null" ] }, "resets_at": { "type": [ "string", "null" ], "format": "date-time" }, "exhausted": { "type": "boolean" } } } } }, "DeploymentBranding": { "type": "object", "properties": { "title": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "heroImageUrl": { "type": "string" }, "accentColor": { "type": "string", "description": "Hex colour like #d97706" }, "starterPrompts": { "type": "array", "items": { "type": "string" }, "maxItems": 8 } } }, "Deployment": { "type": "object", "properties": { "id": { "type": "string" }, "agent_id": { "type": "string" }, "subdomain": { "type": "string" }, "url": { "type": "string" }, "custom_domain": { "type": [ "string", "null" ] }, "custom_domain_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "live", "disabled" ] }, "auth_mode": { "type": "string", "enum": [ "public", "require_login" ] }, "branding": { "$ref": "#/components/schemas/DeploymentBranding" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DeploymentUser": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "first_seen": { "type": "string", "format": "date-time" }, "last_seen": { "type": "string", "format": "date-time" }, "conversations": { "type": "integer" }, "messages": { "type": "integer" }, "blocked": { "type": "boolean" } } }, "DeploymentAnalytics": { "type": "object", "properties": { "days": { "type": "integer" }, "totals": { "type": "object", "properties": { "runs": { "type": "integer" }, "errors": { "type": "integer" }, "conversations": { "type": "integer" }, "users": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cost_usd": { "type": "number" }, "avg_duration_ms": { "type": [ "number", "null" ] } } }, "by_source": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "runs": { "type": "integer" } } } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "runs": { "type": "integer" }, "errors": { "type": "integer" } } } } } }, "DeploymentDomain": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "Custom domains are enabled on this server" }, "domain": { "type": [ "string", "null" ] }, "cname_target": { "type": "string" }, "status": { "type": [ "object", "null" ], "properties": { "verified": { "type": "boolean" }, "misconfigured": { "type": "boolean" }, "verification": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "domain": { "type": "string" }, "value": { "type": "string" }, "reason": { "type": "string" } } } } } } } }, "Skill": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Subagent": { "type": "object", "properties": { "id": { "type": "string", "description": "Tool id" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "agent_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Channel": { "type": "object", "properties": { "id": { "type": "string" }, "agent_id": { "type": "string" }, "deployment_id": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "slack", "telegram", "gmail", "outlook", "teams" ] }, "enabled": { "type": "boolean" }, "status": { "type": "string" }, "slack_channel_id": { "type": [ "string", "null" ] }, "webhook_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Connection": { "type": "object", "properties": { "id": { "type": "string" }, "connector": { "type": "string" }, "label": { "type": "string" }, "auth_kind": { "type": "string" }, "status": { "type": "string" }, "external_account_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Connector": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "auth_kind": { "type": "string" }, "status": { "type": "string", "enum": [ "available", "soon" ] }, "secret_label": { "type": [ "string", "null" ] }, "docs_url": { "type": [ "string", "null" ] } } }, "Member": { "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "joined_at": { "type": "string", "format": "date-time" } } }, "Invite": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "VoiceCall": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "provider": { "type": "string" }, "direction": { "type": [ "string", "null" ] }, "call_sid": { "type": [ "string", "null" ] }, "from_number": { "type": [ "string", "null" ] }, "to_number": { "type": [ "string", "null" ] }, "thread_id": { "type": [ "string", "null" ] }, "agent_version_id": { "type": [ "string", "null" ] }, "stt_provider": { "type": [ "string", "null" ] }, "tts_provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "turns": { "type": [ "integer", "null" ] }, "perceived_p50_ms": { "type": [ "integer", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "has_recording": { "type": "boolean" }, "transcript_lines": { "type": "integer" }, "transcript": { "type": "array", "items": { "type": "object" } } } }, "Screenshot": { "type": "object", "properties": { "seq": { "type": "integer" }, "tool_call_id": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "width": { "type": "integer" }, "height": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "BrowserProfile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "domains": { "type": "array", "items": { "type": "string" } }, "cookieCount": { "type": "integer" }, "signedIn": { "type": "boolean" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastSavedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "BrowserCredential": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "username": { "type": "string" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } } }