{ "openapi": "3.1.0", "info": { "title": "Ocean One API", "version": "2.5.0", "description": "Single front door for the Ocean platform — discovery, tools, agents, workflows, MCP, and model inference. Every response echoes a server-generated x-request-id; pass x-trace-id to correlate across planes. 2.1.0 (Phase 2): the money plane gains ordered model fallback (models[]), sort (price/latency/throughput), retry + 30s outage exclusion with honest billing of the model that actually served, @preset/ addressable configs, per-org/per-key guardrails (spend caps, allow-lists, content filtering, BYOK gates), an opt-in exact-match response cache (x-cache header), and an atomic per-key rate limiter. 2.2.0: one ozk_ key opens every plane (the models plane included); the OpenRouter drop-in base /api/v1; /v1/generation, /v1/credits, /v1/key, /v1/models/{author}/{slug}/endpoints and /v1/completions; tool calls, response_format and images on the Anthropic and Google shapes; passive usage metering and settled billing on streamed aborts. 2.3.0: schedules and triggers over REST — /v1/schedules (create cron or one-time with run_at, list, get, patch, pause/resume, run now, wake, delete, run history) and /v1/triggers (webhook, email and outbound-hook triggers of a schedule); the saved-workflow lifecycle (/v1/workflows, versions), executions (/v1/executions: status, output, continue, steer, cancel, stream), bot control (permissions and budgets, workspace files, inbox, bindings, /v1/bot-groups, /v1/channels), memory, skills and templates, and connections (/v1/connections); POST /v1/execute is the Agent Call door. Three levels, all supported: the compatible wire (tag Compat), the standard REST resources (JSON or YAML), and the Agent Call door. 2.3.1: POST /v1/workflows and PATCH /v1/workflows/{id} also take a text/yaml body (the pure workflow) with kind, name, description and folder as query parameters. 2.4.0: DELETE /v1/companies/{campus} deletes a stopped company and every row of it (204; 409 while it runs), and the company snapshot carries `truncated` (items capped at 500, the door queue at 200). 2.4.1: GET /v1/pricing, the public price list (no key) — per model its list price, Ocean price and headline discount; /v1/models items gain pricing.list, pricing.ocean, pricing.discount_pct, pricing.mode and offers. 2.5.0: POST /v1/messages (and /api/v1/messages), the Anthropic Messages wire on the chat-completions money path — an ozk_ key in x-api-key (security scheme anthropicApiKey) or Authorization: Bearer; errors keep the Anthropic envelope." }, "servers": [ { "url": "https://api.plungeai.com" } ], "components": { "securitySchemes": { "ozkBearer": { "type": "http", "scheme": "bearer", "description": "ozk_ platform API key (Authorization: Bearer ozk_…)" }, "skOcean": { "type": "http", "scheme": "bearer", "description": "Legacy sk-ocean- inference key: still accepted on the money plane until the sk-ocean- sunset; new integrations use the ozk_ key" }, "anthropicApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "ozk_ key in the x-api-key header, as the Anthropic SDKs send it — POST /v1/messages only (Authorization: Bearer also works there and wins when both are sent). anthropic-version is accepted with any value." } }, "schemas": { "UserContext": { "type": "object", "description": "The caller's time zone, locale and location. Optional on every execute body; when absent the gateway derives it from the request's network location (time zone, approximate place). The agent uses it for local time and as the default schedule time zone.", "properties": { "time_zone": { "type": "string", "description": "IANA zone", "example": "America/Los_Angeles" }, "locale": { "type": "string", "description": "BCP-47 tag", "example": "en-US" }, "place": { "type": "string", "example": "San Francisco, California, US" }, "latitude": { "type": "number", "example": 37.7749 }, "longitude": { "type": "number", "example": -122.4194 }, "accuracy_m": { "type": "number", "description": "metres; only with a device GPS fix", "example": 35 }, "source": { "type": "string", "enum": [ "device", "network" ], "example": "device" } }, "required": [ "source" ] }, "Error": { "type": "object", "description": "Standard error envelope. Every error response also carries an `X-Error-Code` response header equal to error.code, so a client branches on the header regardless of the negotiated body format (json | yaml | markdown | text). When the request created an execution, the `X-Execution-Id` response header is also set. Errors follow the negotiated format like success bodies.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "connect": { "type": "object", "description": "On a 424 connection_required / credential_required: where the missing connection is made.", "properties": { "provider": { "type": "string" }, "method": { "type": "string", "enum": [ "oauth", "api_key", "wallet" ] }, "link": { "type": "string", "example": "POST /v1/connections/stripe/link" } } } }, "required": [ "code", "message" ], "additionalProperties": true } }, "required": [ "error" ] }, "Credential": { "description": "The credential an agent runs on. `platform`: our keys, nothing to set up. `connection`: the caller’s own account at `provider` — connect it once with `POST /v1/connections/{provider}` (a key) or `POST /v1/connections/{provider}/link` (a hosted link); without it a call answers 424 with a `connect` pointer.", "oneOf": [ { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "platform" ] } }, "required": [ "tier" ] }, { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "connection" ] }, "provider": { "type": "string" }, "method": { "type": "string", "enum": [ "oauth", "api_key", "wallet" ] } }, "required": [ "tier", "provider", "method" ] } ] }, "Card": { "type": "object", "description": "Registry capability card (summary fields).", "properties": { "id": { "type": "string" }, "credential": { "$ref": "#/components/schemas/Credential", "description": "Present on agent cards (not on skill or connector cards)." }, "name": { "type": "string" }, "type": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "quality": { "description": "Present only when the search was called with include=quality; null when unmeasured (no eval-service binding on this tier, no runs yet, or an upstream miss).", "type": [ "object", "null" ], "properties": { "score": { "type": [ "number", "null" ] }, "success_rate": { "type": [ "number", "null" ] }, "runs": { "type": "integer" } } } }, "required": [ "id", "name", "type", "category", "status" ], "additionalProperties": true }, "ToolContract": { "type": "object", "description": "Exact invocation contract for a tool-agent.", "properties": { "agent_id": { "type": "string" }, "credential": { "$ref": "#/components/schemas/Credential" }, "name": { "type": "string" }, "description": { "type": "string" }, "operations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "purpose": { "type": "string" }, "gated": { "type": "boolean" }, "required_params": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "gated" ] } }, "inputSchema": { "type": "object" }, "examples": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "cnl": { "type": "string" } }, "required": [ "title", "cnl" ] } }, "output_type": { "type": "string" } }, "required": [ "agent_id", "name", "description", "operations", "inputSchema", "examples" ], "additionalProperties": true }, "StoredResult": { "type": "object", "properties": { "content": { "type": "string" }, "content_type": { "type": "string" }, "workflow_id": { "type": "string" }, "task_id": { "type": "string" } }, "required": [ "content" ] }, "McpProtocolTool": { "type": "object", "description": "Standard MCP tool descriptor (JSON-RPC tools/list result item).", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "description": "JSON Schema for the tool arguments" } }, "required": [ "name", "inputSchema" ], "additionalProperties": true }, "McpRunTool": { "type": "object", "description": "Namespaced tool descriptor for an outbound MCP run (mcp-executor).", "properties": { "name": { "type": "string", "description": "Namespaced as mcp____" }, "description": { "type": "string" }, "input_schema": { "type": "object", "description": "JSON Schema for the tool arguments" } }, "required": [ "name", "description", "input_schema" ] }, "Span": { "type": "object", "description": "One row of execution_trace_spans.", "properties": { "id": { "type": "integer" }, "trace_id": { "type": "string" }, "workflow_id": { "type": "string" }, "task_id": { "type": [ "string", "null" ] }, "ts": { "type": "integer" }, "type": { "type": "string", "description": "request_received|task_dispatched|task_completed|workflow_result|…" }, "agent": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "payload_ref": { "type": [ "string", "null" ], "description": "R2 key when large, else null" }, "payload_inline": { "type": [ "string", "null" ], "description": "guard-scanned, <=1KB" } }, "required": [ "id", "trace_id", "workflow_id", "ts", "type" ] }, "MemoryEntry": { "type": "object", "description": "One long-term memory entry. The id is a digest of the store and the text, stable between reads.", "properties": { "id": { "type": "string", "example": "mem_3f9a1c2b7d40" }, "scope": { "type": "string", "enum": [ "memory", "user" ], "description": "memory = your notes; user = your profile" }, "text": { "type": "string" } }, "required": [ "id", "scope", "text" ] }, "Skill": { "type": "object", "description": "A learned skill: a private card that agents inject with `skills: []`.", "properties": { "id": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "description" ] }, "Template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "workflow", "agent", "bot" ] }, "category": { "type": [ "string", "null" ] }, "difficulty": { "type": [ "string", "null" ] }, "usage_count": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "kind" ] }, "GatewayRequest": { "type": "object", "description": "One row of api_gateway_requests — this router’s own request log.", "properties": { "id": { "type": "string" }, "trace_id": { "type": [ "string", "null" ] }, "plane": { "type": "string" }, "route": { "type": "string" }, "user_id": { "type": [ "string", "null" ] }, "status": { "type": "integer" }, "upstream": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "cost_usd": { "type": [ "number", "null" ] }, "created_at": { "type": "integer" } }, "required": [ "id", "plane", "route", "status", "created_at" ] }, "ChatMessage": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ], "example": "user" }, "content": { "type": "string", "example": "Say hi in three words" } }, "required": [ "role", "content" ] }, "ChatCompletionRequest": { "type": "object", "description": "Money plane, ozk_ auth. Transparent proxy to inference-gateway — any OpenAI-compatible field is passed through untouched; the fields below are the ones Phase 2 routing adds on top.", "properties": { "model": { "type": "string", "example": "openai/gpt-4o-mini", "description": "A single model slug (\"provider/model\", e.g. \"anthropic/claude-sonnet-5\"), or \"@preset/\" to expand a stored model+routing+params bundle (request-explicit fields below still override the preset). Required unless models[] is set, which replaces it." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Ordered fallback candidates — alternative to model. One retry per candidate on 429/5xx/network, then failover to the next; a candidate whose provider just failed out is excluded for 30s." }, "sort": { "type": "string", "enum": [ "price", "latency", "throughput" ], "description": "Reorders models[] before the first attempt. latency/throughput sort by rolling provider stats; a provider with no history yet sorts last." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "stream": { "type": "boolean", "default": false }, "temperature": { "type": "number", "description": "Set to exactly 0 to make the request response-cache eligible." }, "max_tokens": { "type": "integer", "example": 16 }, "top_p": { "type": "number" } }, "required": [ "model", "messages" ], "additionalProperties": true }, "ChatCompletionResponse": { "type": "object", "description": "model is the slug that ACTUALLY served the request (honest billing) — it may differ from the requested model/first models[] entry after a failover.", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "model": { "type": "string", "description": "The model that served this response — bill and log both key on this value." }, "choices": { "type": "array", "items": { "type": "object" } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } }, "required": [ "id", "object", "model", "choices" ] }, "AnthropicMessagesRequest": { "type": "object", "description": "Anthropic Messages request (POST /v1/messages), any model slug. On an anthropic/* model the body is forwarded as sent, with only model (the upstream id) and max_tokens (the capped value) set by the gateway, so cache_control, thinking, documents and server tools reach Anthropic unchanged. On any other model it is translated to the chat-completions shape; blocks with no neutral form (thinking, server tools) are not sent. Gateway directives (models, fallbacks, sort, max_cost and OpenRouter's provider, route, transforms, plugins, usage, session_id) are consumed, never forwarded.", "properties": { "model": { "type": "string", "example": "anthropic/claude-haiku-4-5", "description": "A model slug (\"provider/model\") or \"@preset/\". Required unless models[] is set." }, "messages": { "type": "array", "description": "Turns, role user or assistant. content is a string or an array of blocks: text, image (source base64 or url), tool_use, tool_result, thinking, document, … tool_result blocks become tool messages on a translated model.", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicContentBlock" } } ] } }, "required": [ "role", "content" ] }, "example": [ { "role": "user", "content": "Say hi in three words" } ] }, "system": { "description": "A string or an array of text blocks; a system message on a translated model.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/AnthropicContentBlock" } } ] }, "max_tokens": { "type": "integer", "example": 64 }, "stop_sequences": { "type": "array", "items": { "type": "string" }, "description": "stop on a translated model" }, "stream": { "type": "boolean", "default": false }, "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "integer" }, "tools": { "type": "array", "description": "Client tools (name, description, input_schema → function.parameters on a translated model). A server tool (a type other than custom, no input_schema) only an anthropic/* model can run.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "input_schema": { "type": "object" }, "type": { "type": "string" } }, "required": [ "name" ] } }, "tool_choice": { "type": "object", "description": "On a translated model: auto → auto, any → required, none → none, tool → that function; disable_parallel_tool_use → parallel_tool_calls:false.", "properties": { "type": { "type": "string", "enum": [ "auto", "any", "tool", "none" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, "metadata": { "type": "object", "properties": { "user_id": { "type": "string", "description": "user on a translated model" } } }, "thinking": { "type": "object", "description": "Forwarded to anthropic/*. On a translated model, type enabled with budget_tokens becomes reasoning_effort by its share of max_tokens: ≤35% low, ≤65% medium, else high.", "properties": { "type": { "type": "string" }, "budget_tokens": { "type": "integer" } } }, "service_tier": { "type": "string", "description": "standard_only is dropped and auto is forwarded (both the default tier); a value other than auto or default answers 400 unsupported_service_tier (the rate card prices the default tier only)." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Ocean: ordered fallback candidates, as on /v1/chat/completions." }, "fallbacks": { "type": "array", "items": { "type": "string" }, "maxItems": 3, "description": "OpenRouter's Anthropic-skin fallback list: tried after model, at most 3 (more → 400). Ignored when models[] is set." }, "sort": { "type": "string", "enum": [ "price", "latency", "throughput" ] }, "max_cost": { "type": "number", "description": "Ocean: the request’s own cost cap in USD." } }, "required": [ "messages" ], "additionalProperties": true }, "AnthropicContentBlock": { "type": "object", "description": "One Anthropic content block; fields by type.", "properties": { "type": { "type": "string", "example": "text" }, "text": { "type": "string" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64", "url" ] }, "media_type": { "type": "string" }, "data": { "type": "string" }, "url": { "type": "string" } } }, "id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object" }, "tool_use_id": { "type": "string" }, "content": { "description": "tool_result only: a string or an array of text blocks", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] }, "is_error": { "type": "boolean" }, "cache_control": { "type": "object" } }, "required": [ "type" ], "additionalProperties": true }, "AnthropicMessage": { "type": "object", "description": "The Anthropic message the gateway builds from the served completion, for every model (anthropic/* included): content carries text and tool_use blocks. model is the slug that actually served the request.", "properties": { "id": { "type": "string", "example": "msg_0f3c…" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "model": { "type": "string" }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "tool_use" ] }, "text": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object" } }, "required": [ "type" ] } }, "stop_reason": { "type": "string", "enum": [ "end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "refusal" ], "description": "An anthropic/* upstream's own stop reason; otherwise from finish_reason (length → max_tokens, tool_calls → tool_use, content_filter → refusal, else end_turn)." }, "stop_sequence": { "type": "null" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Excludes cache reads and cache writes" }, "output_tokens": { "type": "integer" }, "cache_creation_input_tokens": { "type": "integer" }, "cache_read_input_tokens": { "type": "integer" } } } }, "required": [ "id", "type", "role", "model", "content", "stop_reason", "stop_sequence", "usage" ] }, "AnthropicError": { "type": "object", "description": "Anthropic's error envelope, worn by every POST /v1/messages and /api/v1/messages error the inference gateway answers. error.type follows the HTTP status: 400 invalid_request_error, 401 authentication_error, 402 billing_error, 403 permission_error, 404 not_found_error, 413 request_too_large, 429 rate_limit_error, 504 timeout_error, 529 overloaded_error, any other api_error.", "properties": { "type": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "type": { "type": "string", "example": "authentication_error" }, "message": { "type": "string" } }, "required": [ "type", "message" ] }, "request_id": { "type": "string", "description": "Equals the x-request-id header" } }, "required": [ "type", "error" ] }, "EmbeddingsRequest": { "type": "object", "description": "Money plane, ozk_ auth. Same guardrail/cache enforcement as chat completions.", "properties": { "model": { "type": "string", "example": "openai/text-embedding-3-small" }, "input": { "description": "A string, or an array of strings", "example": "The quick brown fox jumps over the lazy dog" } }, "required": [ "model", "input" ], "additionalProperties": true }, "EmbeddingsResponse": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } }, "model": { "type": "string" }, "usage": { "type": "object" } }, "required": [ "object", "data", "model" ] }, "ModelCatalog": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "description": "Priced model catalog entry (id, pricing, provider)" } } }, "required": [ "object", "data" ] }, "CompatError": { "type": "object", "description": "OpenRouter's error envelope, worn by every /api/v1 error (guide 5.0, 5.7): a numeric `code` equal to the HTTP status, the Ocean detail in `metadata`. No X-Error-Code header.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "The HTTP status" }, "message": { "type": "string" }, "metadata": { "type": "object", "properties": { "error_type": { "type": "string", "description": "OpenRouter's error type: authentication, payment_required, rate_limit_exceeded, not_found, invalid_request, …" }, "ocean_code": { "type": "string", "description": "The /v1 envelope's string error.code" }, "ocean_type": { "type": "string" }, "request_id": { "type": "string", "description": "Equals the x-request-id header" } }, "required": [ "error_type", "ocean_code", "request_id" ], "additionalProperties": true } }, "required": [ "code", "message", "metadata" ], "additionalProperties": true } }, "required": [ "error" ] }, "CompatModelList": { "type": "object", "description": "GET /api/v1/models — OpenRouter's list shape (guide 5.6): no `object`; `links` and `total_count` beside `data`.", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "canonical_slug": { "type": "string" }, "name": { "type": "string" }, "created": { "type": "integer" }, "description": { "type": "string" }, "context_length": { "type": [ "integer", "null" ] }, "architecture": { "type": "object" }, "pricing": { "type": "object", "description": "USD per token, as decimal strings", "properties": { "prompt": { "type": "string" }, "completion": { "type": "string" }, "input_cache_read": { "type": "string" }, "input_cache_write": { "type": "string" } }, "required": [ "prompt", "completion" ] }, "top_provider": { "type": "object" }, "per_request_limits": { "type": [ "object", "null" ] }, "supported_parameters": { "type": "array", "items": { "type": "string" } }, "default_parameters": { "type": [ "object", "null" ] }, "links": { "type": "object", "properties": { "details": { "type": "string" } } }, "supported_voices": { "type": [ "array", "null" ] } }, "required": [ "id", "canonical_slug", "name", "pricing" ] } }, "links": { "type": "object", "properties": { "next": { "type": [ "string", "null" ] } } }, "total_count": { "type": "integer" } }, "required": [ "data", "links", "total_count" ] } } }, "paths": { "/health": { "get": { "operationId": "get-health", "summary": "Liveness probe", "security": [], "responses": { "200": { "description": "Router is up", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } } } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Meta" ], "x-docs-slug": "health" } }, "/v1/openapi.json": { "get": { "operationId": "get-v1-openapi-json", "summary": "This document", "security": [], "responses": { "200": { "description": "OpenAPI spec", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Meta" ], "x-docs-slug": "get-openapi-spec" } }, "/v1/whoami": { "get": { "operationId": "get-v1-whoami", "summary": "The identity behind the calling ozk_ key: user id, tier and key label", "security": [ { "ozkBearer": [] } ], "responses": { "200": { "description": "Caller identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "via": { "type": "string", "enum": [ "key", "internal" ] }, "tier": { "type": [ "string", "null" ] }, "key_label": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Meta" ], "x-docs-slug": "get-whoami" } }, "/v1/discovery/search": { "get": { "operationId": "get-v1-discovery-search", "summary": "Search the capability registry (hybrid semantic + keyword)", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Natural-language capability query" }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "agents", "skills", "digital-twins", "personas", "experts", "backgrounds", "workflows", "models", "providers", "connectors", "plugins", "mcp-servers" ] }, "description": "Plural capability group, e.g. agents, mcp-servers" }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "default": "active" } }, { "name": "tier", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "hybrid", "keyword", "vector" ] } }, { "name": "fields", "in": "query", "schema": { "type": "string", "enum": [ "list", "summary", "full" ] } } ], "responses": { "200": { "description": "Registry search envelope", "content": { "application/json": { "schema": { "type": "object", "properties": { "cards": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "count": { "type": "integer", "description": "Cards in this page." }, "total": { "type": "integer", "description": "Every card the filters match, ignoring limit/offset." }, "searchMethod": { "type": "string" } } } } } }, "401": { "description": "Missing/invalid ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Discovery" ], "x-docs-slug": "search-registry" } }, "/v1/discovery/recommend": { "post": { "operationId": "post-v1-discovery-recommend", "summary": "Recommend the best capability card for a task", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "task": { "type": "string" } }, "required": [ "type", "task" ] } } } }, "responses": { "200": { "description": "Recommendation", "content": { "application/json": { "schema": { "type": "object", "properties": { "recommended": { "type": [ "string", "null" ], "description": "null when nothing matches" }, "card": { "oneOf": [ { "$ref": "#/components/schemas/Card" }, { "type": "null" } ], "description": "null when nothing matches" }, "score": { "type": "number", "description": "0 when nothing matches" } } } } } }, "400": { "description": "invalid_json / invalid_request — malformed or rejected body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Discovery" ], "x-docs-slug": "recommend-card" } }, "/v1/discovery/resolve": { "post": { "operationId": "post-v1-discovery-resolve", "summary": "Resolve a task to one tool, its operation and an example call, with a calibrated confidence", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "string", "description": "What you want done, in plain language" }, "kinds": { "type": "array", "items": { "type": "string" }, "maxItems": 8, "description": "Card types to consider (agent, workflow, connector, mcp_server, skill, plugin, …); plural kinds are accepted aliases. Default: every discoverable kind" }, "category": { "type": "string" }, "status": { "type": "string", "default": "active" } }, "required": [ "task" ] } } } }, "responses": { "200": { "description": "Resolve decision", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "match", "uncertain", "none" ] }, "tool": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" } } }, "operation": { "type": "object", "properties": { "name": { "type": "string" }, "purpose": { "type": "string" }, "gated": { "type": "boolean" } } }, "call": { "type": "object", "properties": { "required_params": { "type": "array", "items": { "type": "string" } }, "example_cnl": { "type": "string" } } }, "confidence": { "type": [ "number", "null" ], "description": "null on the keyword fallback (decision model unavailable)" }, "alternatives": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "p": { "type": "number" } } } }, "mode": { "type": "string", "enum": [ "shadow", "act" ] } } } } } }, "400": { "description": "invalid_json — body missing or no task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Discovery" ], "x-docs-slug": "resolve-task" } }, "/v1/discovery/cards/{type}/{id}": { "get": { "operationId": "get-v1-discovery-cards-type-id", "summary": "Fetch a capability card (markdown LLM view)", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "agent", "skill", "digital_twin", "expert", "background", "workflow", "model", "provider", "connector", "plugin", "mcp_server" ] }, "description": "Singular card type; plural search kinds (agents, mcp-servers, …) are accepted aliases" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_request — a bad type/id is normalised to the One-API error envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no such card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Discovery" ], "x-docs-slug": "get-card" } }, "/v1/tools": { "get": { "operationId": "get-v1-tools", "summary": "List active tool-agents", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Active tool list", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "count": { "type": "integer" } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Tools" ], "x-docs-slug": "list-tools" } }, "/v1/tools/{id}": { "get": { "operationId": "get-v1-tools-id", "summary": "Get a tool contract (JSON Schema params, operations, gates, examples)", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolContract" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_tool; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Tools" ], "x-docs-slug": "get-tool-contract" } }, "/v1/tools/{id}/execute": { "post": { "operationId": "post-v1-tools-id-execute", "summary": "Execute a tool operation (fenced: gated/money verbs refuse unattended)", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Operation fields may be sent bare at the root (`{\"expression\": \"7*6\"}`); `params` is still accepted and wins on a name clash.", "properties": { "operation": { "type": "string", "description": "Operation name from the contract" }, "params": { "type": "object", "description": "Operation params per the contract inputSchema" }, "prompt": { "type": "string", "description": "Free-text prompt for prompt-driven agents" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } } } }, "responses": { "200": { "description": "Execution result Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "content": { "type": "string" }, "outcome": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "ok", "content" ] } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "refused — fence/gated operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_tool; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "approval_required — needs a human approval surface; duplicate_execution_id — x-trace-id already used by an earlier run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — needs_input; body carries missing/reserved + the contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "424": { "description": "connection_required / credential_required — the agent runs on the caller’s own account and none is connected; `error.connect` names the provider and the route that connects it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "execution_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "agent_unavailable — agent temporarily down", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Tools" ], "x-docs-slug": "execute-tool" } }, "/v1/agents": { "get": { "operationId": "get-v1-agents", "summary": "List active agents", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Active agent list", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "count": { "type": "integer" } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Agents" ], "x-docs-slug": "list-agents" } }, "/v1/agents/categories": { "get": { "operationId": "get-v1-agents-categories", "summary": "Agent categories with active-agent counts (aggregated from the registry)", "security": [ { "ozkBearer": [] } ], "responses": { "200": { "description": "Categories envelope", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "count": { "type": "integer" } } } }, "count": { "type": "integer" } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Agents" ], "x-docs-slug": "list-agent-categories" } }, "/v1/agents/{id}/execute": { "post": { "operationId": "post-v1-agents-id-execute", "summary": "Execute an agent with a prompt (sync by default; sync:false returns a pointer)", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Required unless `messages` has a user turn (then the last one is used)" }, "input": { "type": "string", "description": "Alias for prompt" }, "persona": { "type": "string" }, "provider": { "type": "string", "description": "Provider id (anthropic, openai, gemini, …); required alongside a pinned model" }, "model": { "type": "string" }, "maxTokens": { "type": "integer", "description": "Max output tokens (alias: max_tokens)" }, "max_tokens": { "type": "integer", "description": "Alias for maxTokens" }, "temperature": { "type": "number", "description": "Sampling temperature, forwarded to the provider" }, "top_p": { "type": "number", "description": "Nucleus sampling probability, forwarded to the provider" }, "reasoning_effort": { "type": "string", "description": "Reasoning-effort hint (e.g. low/medium/high) for reasoning models" }, "thinking_level": { "type": "string", "description": "Extended-thinking level hint for models that support it" }, "system": { "type": "string", "description": "System prompt / instructions for the run" }, "messages": { "type": "array", "description": "Prior chat messages ([{role, content}]); `prompt` is optional when it has a user turn. one-agent answers from the whole conversation", "items": { "type": "object" } }, "sync": { "type": "boolean", "default": true }, "stream": { "type": "boolean", "default": false, "description": "When true, the response is an OpenAI-shaped chat.completion.chunk SSE (see the 200 text/event-stream variant) instead of a JSON result. Ignored by the async pointer path." }, "user_context": { "$ref": "#/components/schemas/UserContext" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } } } }, "responses": { "200": { "description": "Resolved result. Default (stream absent/false): a JSON result object. With stream:true: an OpenAI-shaped chat.completion.chunk SSE — one primer chunk carrying delta.role=\"assistant\", then a delta.content chunk per provider token, then a final chunk with delta:{} and finish_reason \"stop\" (or \"length\" when the model was truncated at max_tokens), then a literal `data: [DONE]` line. usage is emitted on the final chunk only when the provider reports the prompt/completion split (often omitted for streamed runs). Comment keepalives (`: OCEAN PROCESSING`) may appear every ~15s while idle. Errors before the first byte are the normal JSON error envelopes below (not SSE); an error after the first byte is a single `data: {\"error\":{…}}` frame and the stream closes WITHOUT `[DONE]`. Response header X-Execution-Id carries the execution id for result redemption / polling. Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "workflow_id": { "type": "string" }, "task_id": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "content" ] } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } }, "text/event-stream": { "schema": { "type": "string" }, "example": "data: {\"id\":\"chatcmpl-e2222ee13ea2499a95105245\",\"object\":\"chat.completion.chunk\",\"created\":1788574344,\"model\":\"one-agent\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\"},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-e2222ee13ea2499a95105245\",\"object\":\"chat.completion.chunk\",\"created\":1788574344,\"model\":\"one-agent\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"391\"},\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-e2222ee13ea2499a95105245\",\"object\":\"chat.completion.chunk\",\"created\":1788574344,\"model\":\"one-agent\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}]}\n\ndata: [DONE]\n\n" } } }, "202": { "description": "Accepted (async) — redeem via /v1/agents/results/{workflowId}/{taskId}", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow_id": { "type": "string" }, "task_id": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "400": { "description": "missing_prompt / invalid_json / invalid_yaml / invalid_body (unreadable body) / invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "agent_not_active — the agent card is not status:active (refused pre-dispatch)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_agent — no such agent id in the registry (refused pre-dispatch); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "duplicate_execution_id — x-trace-id already used by an earlier run — send a fresh UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — needs_input (the agent named a missing/invalid input); unknown_model (pinned model absent/inactive in the catalog); empty_completion (the run completed but the model returned no visible content — raise max_tokens ≥ 64 or change the model)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "424": { "description": "connection_required / credential_required — the agent runs on the caller’s own account and none is connected; `error.connect` names the provider and the route that connects it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "engine_error / result_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "agent_unavailable — agent temporarily down", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Agents" ], "x-docs-slug": "execute-agent" } }, "/v1/agents/results/{workflowId}/{taskId}": { "get": { "operationId": "get-v1-agents-results-workflowid-taskid", "summary": "Redeem an async agent result", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stored result Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredResult" } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_ready — the result is not stored yet (still running): poll again; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "execution_failed — the run failed; the message is the run error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "empty_completion — the run completed but produced no visible content (hint: max_tokens >= 64)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Agents" ], "x-docs-slug": "get-agent-result" } }, "/v1/execute": { "post": { "operationId": "post-v1-execute", "tags": [ "Agent Call" ], "summary": "Agent Call — a bare building block, a workflow, or a saved agent (agent: [@n]) in one body", "description": "The body is the program. Always runs through the engine, so a saved bot keeps its stored policy. `agent: ` runs the key owner's saved agent (live YAML), `agent: @n` its snapshot n; any other `agent:` is a registry building block and the other root fields are its task fields. `format`, `input`, `inputs`, `user_context`, `stream`, `dry_run` and `on_behalf_of` are wire keys and never reach the agent. The standard REST routes (`/v1/workflows/{id}/execute`, `/v1/agents/{id}/execute`, …) are unchanged. Accepted bodies, JSON (`application/json`) or YAML (any other Content-Type, `text/yaml` included): (1) `agent: [@n]` plus `input` / `inputs` — a saved agent or a registry building block; (2) `workflow:` as an object, a YAML string, or a `workflow:` envelope; (3) `tasks:` at the root, with an optional `name:` (nested as a workflow; a falsy or null `workflow:` next to it counts as absent); (4) in YAML, the workflow itself at the root (`name:` + `tasks:`), including flow style and CRLF; every body the inline execute routes (`/v1/workflows/execute`, `/v1/cnl/execute`) accept runs here too. The pre-router SDK bodies `{\"direct\":{…}}` and `workflow_id:` were never accepted by the router and answer 400; run a saved workflow with `agent: `.", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string", "description": "a saved agent id (`` live, `@n` snapshot n; takes only the wire keys) or a registry building block id (every other field is passed to it)" }, "workflow": { "description": "CNL workflow object, or a YAML string" }, "name": { "type": "string", "description": "with `tasks`: the workflow name" }, "tasks": { "type": "array", "description": "the task list, auto-nested as a workflow" }, "input": { "type": "string" }, "inputs": { "type": "object" }, "user_context": { "$ref": "#/components/schemas/UserContext" }, "stream": { "type": "boolean", "description": "true: answer as SSE (text/event-stream), whatever `format` says" }, "dry_run": { "type": "boolean", "description": "true: validate and resolve only — 200 {dry_run, kind, agent, tasks:[{id, agent, type}], warnings}; no run, no execution row" }, "on_behalf_of": { "type": "string", "pattern": "^(?!.*\\.\\.)[A-Za-z0-9_.-]{1,128}$", "description": "Run as one of your customers: a connection-tier agent uses the account connected under this id (`POST /v1/connections/{provider}` or its `/link`) instead of yours. The run, its billing and a saved agent stay yours." }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Engine acknowledgement (or the dry_run report). Headers: x-ocean-agent (saved agent or building block id; absent for an inline workflow), x-ocean-tasks (top-level task count), x-ocean-version (the snapshot number the pinned run used; for an unpinned saved agent the live YAML ran and the header carries the newest snapshot; `live` for a saved agent with no snapshot, `inline` otherwise), x-ocean-run (`customer` when `on_behalf_of` names a customer, else `platform`; on every engine-plane response, refusals included) Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "workflow_id": { "type": "string" }, "final_task_id": { "type": "string" }, "request_id": { "type": "string" }, "content": { "type": "string", "description": "the final task's stored content" }, "dry_run": { "type": "boolean" }, "kind": { "type": "string", "description": "dry_run: bot | agent | workflow | campaign for a saved agent, workflow for an inline one, task for a building block" }, "agent": { "type": [ "string", "null" ] }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "agent": { "type": [ "string", "null" ] }, "type": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "missing_workflow / ambiguous_body (building block next to workflow or tasks) / reserved_field / invalid_body (an unreadable body, extra fields next to a saved agent, an `agent` that is not an id[@n], a `dry_run` / `stream` that is not a boolean, or a wire key inside a `params:` wrapper — `params: {…}` is otherwise unwrapped into the task) / invalid_json / invalid_yaml / invalid_format / invalid_on_behalf_of / invalid_workflow (dry_run: the validator's errors)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "agent_not_active — a named agent card is not status:active (refused pre-dispatch)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "agent_not_found — `agent:` names no saved agent of this key (or snapshot) and no building block; unknown_agent — a workflow names an agent the registry does not know; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "duplicate_execution_id — x-trace-id already used by an earlier run; not_executable — `agent:` names a saved campus or building document, which is compiled by POST /v1/companies/{campus}/apply, never executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "engine_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "agent-call" } }, "/v1/workflows/execute": { "post": { "operationId": "post-v1-workflows-execute", "tags": [ "Workflows" ], "summary": "Execute an inline workflow (JSON {workflow, input} or raw YAML body)", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "One of three shapes: a bare agent call (`agent` + the agent's own fields), a `workflow` object or YAML string, or top-level `name`/`tasks` (auto-nested). `format`, `input`, `inputs`, `user_context`, `stream`, `sync`, `dry_run` and `metadata` are wire keys and never reach the agent.", "properties": { "agent": { "type": "string", "description": "bare agent call: the agent id; every other field is passed to the agent (guide 10.2)" }, "workflow": { "description": "CNL workflow object, or a YAML string" }, "name": { "type": "string", "description": "with `tasks`: the workflow name" }, "tasks": { "type": "array", "description": "with `name`: the task list, auto-nested under `workflow`" }, "input": { "type": "string" }, "inputs": { "type": "object" }, "user_context": { "$ref": "#/components/schemas/UserContext" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Engine acknowledgement Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "workflow_id": { "type": "string" }, "final_task_id": { "type": "string" }, "request_id": { "type": "string" }, "content": { "type": "string", "description": "the final task's stored content, present once the sync run has stored it" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "missing_workflow (none of workflow / agent / tasks) / ambiguous_body (agent next to workflow or tasks) / reserved_field (a field named like an engine task key) / invalid_json / invalid_yaml / invalid_body (unreadable body) / invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "agent_not_active — a named agent card is not status:active (refused pre-dispatch)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_agent — a named agent id does not exist in the registry (refused pre-dispatch); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "duplicate_execution_id — x-trace-id already used by an earlier run — send a fresh UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "engine_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "execute-inline-workflow" } }, "/v1/workflows/execute-stream": { "post": { "operationId": "post-v1-workflows-execute-stream", "tags": [ "Workflows" ], "summary": "Execute an inline workflow (YAML or JSON) with SSE event streaming", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "description": "CNL workflow object, or a YAML string" }, "input": { "type": "string" }, "inputs": { "type": "object" }, "user_context": { "$ref": "#/components/schemas/UserContext" } }, "required": [ "workflow" ] } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "SSE stream: request_received, workflow_loaded, workflow_started, task_dispatched, streaming_started (streaming agents), token (one frame per provider delta: {\"task_id\",\"delta\"}), heartbeat, task_completed, then workflow_completed (the outcome, carries execution_summary; workflow_error on failure) and workflow_result, always the last frame. Single connection: the gateway drains the provider stream itself; terminal events always arrive on this SSE.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "missing_workflow / invalid_json / invalid_body (unreadable body) / invalid_workflow / invalid_yaml — refusals before the first frame are this JSON envelope, never an SSE frame", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "agent_not_active — a named agent card is not status:active (refused pre-dispatch)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_agent — a named agent id does not exist in the registry (refused pre-dispatch); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "engine_error — the engine refused the stream before its first frame", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "stream-inline-workflow" } }, "/v1/workflows/{id}/execute": { "post": { "operationId": "post-v1-workflows-id-execute", "tags": [ "Workflows" ], "summary": "Execute a saved workflow (loaded from the engine KV by id + your user)", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string" }, "inputs": { "type": "object" }, "user_context": { "$ref": "#/components/schemas/UserContext" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } } } }, "responses": { "200": { "description": "Engine acknowledgement Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "workflow_id": { "type": "string" }, "final_task_id": { "type": "string" }, "request_id": { "type": "string" }, "content": { "type": "string", "description": "the final task's stored content, present once the sync run has stored it" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this key; unknown_agent — the saved workflow names an agent the registry does not know (refused pre-dispatch); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "duplicate_execution_id — x-trace-id already used by an earlier run — send a fresh UUID; not_executable — the id names a saved campus or building document, which is compiled by POST /v1/companies/{campus}/apply, never executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "engine_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "execute-saved-workflow" } }, "/v1/workflows/{id}/execute-stream": { "post": { "operationId": "post-v1-workflows-id-execute-stream", "tags": [ "Workflows" ], "summary": "Execute a saved workflow with SSE event streaming", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string" }, "inputs": { "type": "object" }, "user_context": { "$ref": "#/components/schemas/UserContext" } } } } } }, "responses": { "200": { "description": "SSE stream: request_received, workflow_loaded, workflow_started, task_dispatched, streaming_started (streaming agents), token (one frame per provider delta: {\"task_id\",\"delta\"}), heartbeat, task_completed, then workflow_completed (the outcome, carries execution_summary; workflow_error on failure) and workflow_result, always the last frame. Single connection: the gateway drains the provider stream itself; terminal events always arrive on this SSE.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_workflow — the saved workflow failed the engine structural check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this key; unknown_agent — the saved workflow names an agent the registry does not know (refused pre-dispatch). The JSON envelope, never an SSE frame; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "not_executable — the id names a saved campus or building document, which is compiled by POST /v1/companies/{campus}/apply, never executed. The JSON envelope, never an SSE frame", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "engine_error — the engine refused the stream before its first frame", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "stream-saved-workflow" } }, "/v1/workflows/results/{workflowId}/{taskId}": { "get": { "operationId": "get-v1-workflows-results-workflowid-taskid", "tags": [ "Workflows" ], "summary": "Redeem a workflow task result from SharedMemory", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stored result Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredResult" } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_ready — the result is not stored yet (still running): poll again; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "execution_failed — the run failed; the message is the run error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "empty_completion — the run completed but produced no visible content (hint: max_tokens >= 64)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-workflow-result" } }, "/v1/workflows/executions/{id}/cancel": { "post": { "operationId": "post-v1-workflows-executions-id-cancel", "tags": [ "Workflows" ], "summary": "Cancel a running workflow execution (cooperative)", "description": "Writes the SharedMemory cancel marker the engine and agent loops poll at their next turn/tool boundary, and stamps the row cancelled. Wrong owner → 404 (no existence leak); not running → 409. Since /v1/workflows/execute is synchronous, pass your own x-trace-id on the execute call and use it as {id} here.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "cancelled": { "type": "string", "description": "The execution id" }, "markers": { "type": "array", "items": { "type": "string" }, "description": "Run ids the cancel marker was written under (row id + engine cln id)" } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no such execution for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "not_running — the execution already finished or was cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "cancel-execution" } }, "/v1/workflows": { "get": { "operationId": "get-v1-workflows", "tags": [ "Workflows" ], "summary": "List your saved workflows, agents, bots, campaigns, campuses and buildings", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Case-insensitive name substring (plain text: % and _ are literal)" }, { "name": "folder", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Exact folder name, case-insensitive" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Your workflows, newest update first Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] }, "description": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ], "description": "The folder name, or null when unfiled" }, "updated_at": { "type": "integer", "description": "Unix seconds" }, "version": { "type": [ "integer", "null" ], "description": "Number of the current saved version; null until a version is saved" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — kind, limit or offset is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "storage_error — the database or storage layer failed; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-workflows" }, "post": { "operationId": "post-v1-workflows", "tags": [ "Workflows" ], "summary": "Save a workflow, agent, bot, campaign, campus or building", "description": "The same row Studio and the MCP tools show. `yaml` is validated against the CNL schema and the kind lint before anything is stored (a bot on a frozen runtime such as harness-agent with `posture` is refused). `folder` names an existing folder or creates it. A `kind: campaign` create with `campaign_config` also sets up the ledger and the schedule. `kind: campus` and `kind: building` save company documents (a campus names its buildings, a building its pipeline); they are compiled by POST /v1/companies/{campus}/apply and never executed. Save as YAML: send the pure workflow YAML as a `text/yaml` body and the metadata as the `kind` (required), `name` (required unless `workflow.name` is in the YAML), `description` and `folder` query parameters; a YAML body without `kind` is 400 `invalid_request`, and `campaign_config` stays JSON-only.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] }, "description": "text/yaml body only. Required on create; on PATCH it must equal the stored kind or be left out (400 invalid_request otherwise; change a kind with a JSON PATCH)" }, { "name": "name", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "text/yaml body only. Create: required unless `workflow.name` is in the YAML (the query wins when both are set). PATCH: renames" }, { "name": "description", "in": "query", "schema": { "type": "string" }, "description": "text/yaml body only. Optional" }, { "name": "folder", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "text/yaml body only. Optional; the same as the JSON `folder` field" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "kind", "yaml" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "kind": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] }, "yaml": { "type": "string", "description": "The workflow as CNL YAML" }, "description": { "type": "string" }, "folder": { "type": "string", "maxLength": 120 }, "campaign_config": { "type": "object", "description": "kind campaign only (422 on any other kind). list (exactly one of table | agent | csv | inline), cycle (once | hourly | daily | weekly | monthly | continuous) and max_attempts (integer >= 1) are required; cycle_start (reset | refill), schedule (5-field cron), batch_size, max_items, pace, then (a campaign or workflow id), deliver ([{ channel, to?, chat_id?, phone_number_id? }] — in-app, email, slack, telegram, discord, whatsapp, teams; telegram/discord need chat_id, whatsapp needs to + phone_number_id, teams a Graph target; default in-app), task_types (object), learn ({ variants, max_revisions, policy: thompson | ucb | epsilon, revise: manual | auto, context, approve }) and local are optional — the Studio campaign-config block, parsed by the same validator Studio uses. Invalid → 422 invalid_params, nothing is created." }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } }, "text/yaml": { "schema": { "type": "string", "description": "The workflow as CNL YAML, `workflow:` at the top (also application/yaml and application/x-yaml); the other fields are the `kind`, `name`, `description` and `folder` query parameters. The reply stays JSON unless `format` or Accept say otherwise." } } } }, "responses": { "201": { "description": "Saved; the Location header names the new workflow. Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] }, "description": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ], "description": "The folder name, or null when unfiled" }, "updated_at": { "type": "integer", "description": "Unix seconds" }, "version": { "type": [ "integer", "null" ], "description": "Number of the current saved version; null until a version is saved" } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal notes (lint warnings, campaign setup notes); present only when there are any" }, "ledger_id": { "type": "string", "description": "kind campaign only: the campaign ledger that was created" }, "job_id": { "type": "string", "description": "kind campaign only: the scheduled job that was created (absent when the config has no schedule)" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_workflow — the YAML failed validation or the kind lint (the envelope carries `errors` and `warnings`; nothing was written). invalid_params — a field is missing or malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "storage_error — the database or storage layer failed; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "create-workflow" } }, "/v1/workflows/{id}": { "get": { "operationId": "get-v1-workflows-id", "tags": [ "Workflows" ], "summary": "Read one saved workflow with its YAML", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The workflow row and its live YAML Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] }, "description": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ], "description": "The folder name, or null when unfiled" }, "updated_at": { "type": "integer", "description": "Unix seconds" }, "version": { "type": [ "integer", "null" ], "description": "Number of the current saved version; null until a version is saved" } } }, "yaml": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "storage_error — the database or storage layer failed; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-workflow" }, "patch": { "operationId": "patch-v1-workflows-id", "tags": [ "Workflows" ], "summary": "Change a workflow: name, description, YAML, kind or folder", "description": "Send any of the fields. The YAML (the new one, or the stored one when only `kind` changes) is linted against the kind the row will have afterwards; a rejected patch changes nothing. JSON `null` on `description` or `folder` clears it (`folder: \"none\"` unfiles too); `null` on any other field is a 422. A `kind` that moves away from `bot` or `campaign` runs the delete teardown for the old kind: a bot loses its memory namespace and its scheduled jobs, a campaign loses its jobs and its ledger is tombstoned (the row itself stays). Save as YAML: a `text/yaml` body is the new workflow YAML and `name`, `description` and `folder` ride the query; `kind` must equal the stored kind or be left out (400 `invalid_request`).", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] }, "description": "text/yaml body only. Required on create; on PATCH it must equal the stored kind or be left out (400 invalid_request otherwise; change a kind with a JSON PATCH)" }, { "name": "name", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "text/yaml body only. Create: required unless `workflow.name` is in the YAML (the query wins when both are set). PATCH: renames" }, { "name": "description", "in": "query", "schema": { "type": "string" }, "description": "text/yaml body only. Optional" }, { "name": "folder", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "text/yaml body only. Optional; the same as the JSON `folder` field" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "description": "null clears it" }, "yaml": { "type": "string" }, "kind": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] }, "folder": { "type": [ "string", "null" ], "maxLength": 120, "description": "null (or \"none\") unfiles" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } }, "text/yaml": { "schema": { "type": "string", "description": "The workflow as CNL YAML, `workflow:` at the top (also application/yaml and application/x-yaml); the other fields are the `kind`, `name`, `description` and `folder` query parameters. The reply stays JSON unless `format` or Accept say otherwise." } } } }, "responses": { "200": { "description": "The updated row Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] }, "description": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ], "description": "The folder name, or null when unfiled" }, "updated_at": { "type": "integer", "description": "Unix seconds" }, "version": { "type": [ "integer", "null" ], "description": "Number of the current saved version; null until a version is saved" } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal notes (lint warnings, campaign setup notes); present only when there are any" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large — body over 1 MiB (MAX_REQUEST_SIZE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_workflow — the YAML failed validation or the kind lint (the envelope carries `errors` and `warnings`; nothing was written). invalid_params — a field is missing or malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "storage_error — the database or storage layer failed; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "update-workflow" }, "delete": { "operationId": "delete-v1-workflows-id", "tags": [ "Workflows" ], "summary": "Delete a workflow", "description": "A bot also loses its memory namespace and its scheduled jobs; a campaign also loses its jobs and its ledger is tombstoned. 204 with no body.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "storage_error — the database or storage layer failed; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "delete-workflow" } }, "/v1/workflows/{id}/versions": { "get": { "operationId": "get-v1-workflows-id-versions", "tags": [ "Workflows" ], "summary": "List the saved versions of a workflow, newest first", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Versions Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "timestamp": { "type": "integer", "description": "Unix seconds" }, "description": { "type": [ "string", "null" ], "description": "The label given when the version was saved" } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "storage_error — the database or storage layer failed; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-workflow-versions" }, "post": { "operationId": "post-v1-workflows-id-versions", "tags": [ "Workflows" ], "summary": "Save the current YAML as a new version", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 200 }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } } } }, "responses": { "201": { "description": "Saved. Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "timestamp": { "type": "integer", "description": "Unix seconds" }, "description": { "type": [ "string", "null" ], "description": "The label given when the version was saved" } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — label is not a string of at most 200 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "storage_error — the database or storage layer failed; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "save-workflow-version" } }, "/v1/workflows/{id}/versions/{versionId}/restore": { "post": { "operationId": "post-v1-workflows-id-versions-versionid-restore", "tags": [ "Workflows" ], "summary": "Make a saved version the live YAML again", "description": "The version is linted against the workflow's current kind first; the restore is then recorded as a new version.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The workflow after the restore Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "workflow", "agent", "bot", "campaign", "campus", "building" ] }, "description": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ], "description": "The folder name, or null when unfiled" }, "updated_at": { "type": "integer", "description": "Unix seconds" }, "version": { "type": [ "integer", "null" ], "description": "Number of the current saved version; null until a version is saved" } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this key; version_not_found — no such version of it; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_workflow — the YAML failed validation or the kind lint (the envelope carries `errors` and `warnings`; nothing was written). invalid_params — a field is missing or malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "storage_error — the database or storage layer failed; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "restore-workflow-version" } }, "/v1/mcp/tools": { "get": { "operationId": "get-v1-mcp-tools", "summary": "List the platform-as-MCP-server tools (JSON-RPC tools/list, signed pass-through)", "security": [ { "ozkBearer": [] } ], "responses": { "200": { "description": "JSON-RPC tools/list result", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "id": { "type": "integer" }, "result": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpProtocolTool" } } } } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "MCP" ], "x-docs-slug": "list-mcp-tools" } }, "/v1/mcp": { "post": { "operationId": "post-v1-mcp", "summary": "Inbound MCP Streamable-HTTP pass-through — point any MCP client here with an ozk_ key", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 message" } } } }, "responses": { "200": { "description": "JSON-RPC response (JSON, or SSE for streamed tool calls)", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 response" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Parse error — the body is not valid JSON: a JSON-RPC 2.0 error (code -32700), not the router envelope", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "id": { "type": "null" } }, "required": [ "jsonrpc", "error" ] } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "MCP" ], "x-docs-slug": "mcp-endpoint" } }, "/v1/mcp/runs": { "post": { "operationId": "post-v1-mcp-runs", "summary": "Open an outbound MCP run: connect catalog servers, get their tool table", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "server_ids": { "type": "array", "items": { "type": "string" }, "description": "Registry mcp-server card ids" } }, "required": [ "server_ids" ] } } } }, "responses": { "201": { "description": "Run opened", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpRunTool" } }, "connected": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "invalid_json / invalid_body — body is not JSON, or `server_ids` is not a non-empty string array", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "no_servers_connected (body carries per-server failures)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "MCP" ], "x-docs-slug": "create-mcp-run" } }, "/v1/mcp/runs/{id}/tools": { "get": { "operationId": "get-v1-mcp-runs-id-tools", "summary": "List an MCP run's namespaced tools", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tool table", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpRunTool" } }, "count": { "type": "integer" } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "run_not_found — no MCP run with that id for this key: never opened, closed, or expired after 30 min idle. Open a new run; retrying never revives it; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "MCP" ], "x-docs-slug": "list-mcp-run-tools" } }, "/v1/mcp/runs/{id}/call": { "post": { "operationId": "post-v1-mcp-runs-id-call", "summary": "Call one namespaced tool in an MCP run", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Namespaced tool name (mcp____)" }, "args": { "type": "object" }, "timeout_ms": { "type": "integer" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" } } } } } }, "400": { "description": "invalid_json / invalid_body — body is not JSON, or `name` is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "run_not_found — no MCP run with that id for this key: never opened, closed, or expired after 30 min idle. Open a new run; retrying never revives it; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited — Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "tool_call_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "MCP" ], "x-docs-slug": "call-mcp-run-tool" } }, "/v1/mcp/runs/{id}": { "delete": { "operationId": "delete-v1-mcp-runs-id", "summary": "Close an MCP run (drop the run's Durable Object state; idempotent)", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cleared", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "MCP" ], "x-docs-slug": "close-mcp-run" } }, "/v1/traces/{id}": { "get": { "operationId": "get-v1-traces-id", "summary": "Persisted execution trace — spans + gateway request log for one trace id", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trace", "content": { "application/json": { "schema": { "type": "object", "properties": { "trace_id": { "type": "string" }, "cost_usd": { "type": [ "number", "null" ], "description": "The execution row’s priced cost (workflow_executions.cost_usd); null until workflow-cost has priced the run" }, "cost_status": { "type": [ "string", "null" ], "enum": [ "priced", "partial", "unpriced", null ] }, "spans": { "type": "array", "items": { "$ref": "#/components/schemas/Span" } }, "gateway_requests": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayRequest" } } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — the id is unknown, or the trace belongs to another key (the same answer for both). Spans and request logs land asynchronously: retry in a few seconds after a run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Traces" ], "x-docs-slug": "get-trace" } }, "/v1/workflows/{id}/permissions": { "get": { "operationId": "get-v1-workflows-id-permissions", "tags": [ "Bots" ], "summary": "A bot’s permission presets, admin locks and spend caps", "description": "The policy the engine applies to every run of the bot, from every door. Owner only.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved workflow id (a bot you own)" } ], "responses": { "200": { "description": "Stored policy and its effective classes Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "classes": { "type": "object", "description": "Stored preset per permission class; a class absent here falls back to the bot YAML / default", "additionalProperties": { "type": "string", "enum": [ "allow", "ask", "deny", "hand_off" ] }, "propertyNames": { "enum": [ "send", "write", "pay", "delete" ] } }, "locks": { "type": "array", "items": { "type": "string", "enum": [ "send", "write", "pay", "delete" ] }, "description": "Admin locks: a locked class forces the bot’s own `allow` up to `ask`" }, "budget_usd_run": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "description": "Per-run spend cap in USD; null = none. 0 is refused (422 invalid_params): a zero cap would stop every run before its first task" }, "budget_usd_month": { "type": [ "number", "null" ], "minimum": 0, "description": "Monthly spend cap in USD; null = none" }, "effective": { "type": "object", "description": "The preset each class runs under: the stored one (the engine applies it on every run, from every door), else `allow` — a class no preset names is let through. A locked class still lifts `allow` to `ask`, and the money floor always asks. `hand_off` is a One Agent verdict; other agent runtimes treat it as `deny`.", "properties": { "send": { "type": "string", "enum": [ "allow", "ask", "deny", "hand_off" ] }, "write": { "type": "string", "enum": [ "allow", "ask", "deny", "hand_off" ] }, "pay": { "type": "string", "enum": [ "allow", "ask", "deny", "hand_off" ] }, "delete": { "type": "string", "enum": [ "allow", "ask", "deny", "hand_off" ] } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this account (foreign and missing ids answer alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-bot-permissions" }, "put": { "operationId": "put-v1-workflows-id-permissions", "tags": [ "Bots" ], "summary": "Set a bot’s permission presets, locks and spend caps", "description": "Each field present replaces the stored one; absent fields stay (budgets: null clears a cap). `locks` can be set only by a team admin over the workflow (project owner or admin, company owner or admin) — anyone else gets 403 and nothing is written.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved workflow id (a bot you own)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "classes": { "type": "object", "description": "Stored preset per permission class; a class absent here falls back to the bot YAML / default", "additionalProperties": { "type": "string", "enum": [ "allow", "ask", "deny", "hand_off" ] }, "propertyNames": { "enum": [ "send", "write", "pay", "delete" ] } }, "locks": { "type": "array", "items": { "type": "string", "enum": [ "send", "write", "pay", "delete" ] }, "description": "Admin locks: a locked class forces the bot’s own `allow` up to `ask`" }, "budget_usd_run": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "description": "Per-run spend cap in USD; null = none. 0 is refused (422 invalid_params): a zero cap would stop every run before its first task" }, "budget_usd_month": { "type": [ "number", "null" ], "minimum": 0, "description": "Monthly spend cap in USD; null = none" } } } }, "text/yaml": { "schema": { "type": "object", "properties": { "classes": { "type": "object", "description": "Stored preset per permission class; a class absent here falls back to the bot YAML / default", "additionalProperties": { "type": "string", "enum": [ "allow", "ask", "deny", "hand_off" ] }, "propertyNames": { "enum": [ "send", "write", "pay", "delete" ] } }, "locks": { "type": "array", "items": { "type": "string", "enum": [ "send", "write", "pay", "delete" ] }, "description": "Admin locks: a locked class forces the bot’s own `allow` up to `ask`" }, "budget_usd_run": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "description": "Per-run spend cap in USD; null = none. 0 is refused (422 invalid_params): a zero cap would stop every run before its first task" }, "budget_usd_month": { "type": [ "number", "null" ], "minimum": 0, "description": "Monthly spend cap in USD; null = none" } } } } } }, "responses": { "200": { "description": "The policy now stored Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "classes": { "type": "object", "description": "Stored preset per permission class; a class absent here falls back to the bot YAML / default", "additionalProperties": { "type": "string", "enum": [ "allow", "ask", "deny", "hand_off" ] }, "propertyNames": { "enum": [ "send", "write", "pay", "delete" ] } }, "locks": { "type": "array", "items": { "type": "string", "enum": [ "send", "write", "pay", "delete" ] }, "description": "Admin locks: a locked class forces the bot’s own `allow` up to `ask`" }, "budget_usd_run": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "description": "Per-run spend cap in USD; null = none. 0 is refused (422 invalid_params): a zero cap would stop every run before its first task" }, "budget_usd_month": { "type": [ "number", "null" ], "minimum": 0, "description": "Monthly spend cap in USD; null = none" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "lock_admin_required — only a team admin over the workflow can set locks; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this account (foreign and missing ids answer alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "set-bot-permissions" } }, "/v1/workflows/{id}/workspace-files": { "get": { "operationId": "get-v1-workflows-id-workspace-files", "tags": [ "Bots" ], "summary": "A bot’s persistent workspace files", "description": "The files the bot keeps between runs (`workspace: bot`), newest first. Owner only.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved workflow id (a bot you own)" } ], "responses": { "200": { "description": "Workspace listing Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "truncated": { "type": "boolean", "description": "More files exist than were listed" }, "workspace_id": { "type": "string", "example": "bot:" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this account (foreign and missing ids answer alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the workspace store is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-workspace-files" } }, "/v1/workflows/{id}/workspace-files/download": { "get": { "operationId": "get-v1-workflows-id-workspace-files-download", "tags": [ "Bots" ], "summary": "Download one workspace file", "description": "Raw bytes with the stored content type (application/octet-stream when unknown), always `Content-Disposition: attachment`. The path must name a listed file inside the workspace: `..`, absolute paths outside /ws and encoded forms are refused.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved workflow id (a bot you own)" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "A path from the listing, e.g. `notes/a.md`" } ], "responses": { "200": { "description": "The file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "invalid_path — path does not name a file inside the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this account (foreign and missing ids answer alike); file_not_found — no such file in the workspace; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "file_too_large — the file is above the 20 MB download limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the workspace store is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "download-workspace-file" } }, "/v1/workflows/{id}/inbox": { "get": { "operationId": "get-v1-workflows-id-inbox", "tags": [ "Bots" ], "summary": "A bot’s inbox", "description": "Queued bot-to-bot messages, newest first; the bot drains them at the start of its next run. Read-only. Owner only.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved workflow id (a bot you own)" } ], "responses": { "200": { "description": "Queued messages Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "from_name": { "type": "string" }, "text": { "type": "string" }, "ts": { "type": "integer" }, "hops": { "type": "integer" }, "group": { "type": "string" } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this account (foreign and missing ids answer alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-bot-inbox" } }, "/v1/workflows/{id}/bindings": { "get": { "operationId": "get-v1-workflows-id-bindings", "tags": [ "Bots" ], "summary": "Chats bound to a bot", "description": "The paired chats (Telegram, WhatsApp, Discord, Teams) that talk to this bot. `pending: true` with an empty list means channel bindings are not enabled yet.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved workflow id (a bot you own)" } ], "responses": { "200": { "description": "Bindings of this bot Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bindings": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "sender_id": { "type": "string" }, "sender_name": { "type": "string" }, "target": { "type": "string", "description": "The bot (workflow) id the chat talks to" }, "target_name": { "type": "string" } }, "required": [ "channel", "sender_id", "target" ] } }, "pending": { "type": "boolean" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this account (foreign and missing ids answer alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — channel bindings are unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-bindings" }, "post": { "operationId": "post-v1-workflows-id-bindings", "tags": [ "Bots" ], "summary": "Bind a paired chat to a bot", "description": "The chat must be one you paired (`POST /v1/channels/pair`); anything else is 422 not_paired. A chat talks to one bot: binding it again moves it.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved workflow id (a bot you own)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "example": "telegram" }, "sender_id": { "type": "string", "maxLength": 128, "description": "The paired chat’s sender id, from GET /v1/channels" } }, "required": [ "channel", "sender_id" ] } } } }, "responses": { "201": { "description": "Bound", "content": { "application/json": { "schema": { "type": "object", "properties": { "binding": { "type": "object", "properties": { "channel": { "type": "string" }, "sender_id": { "type": "string" }, "sender_name": { "type": "string" }, "target": { "type": "string", "description": "The bot (workflow) id the chat talks to" }, "target_name": { "type": "string" } }, "required": [ "channel", "sender_id", "target" ] } } } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this account (foreign and missing ids answer alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "binding_limit — the account has reached its binding limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "not_paired — that chat is not paired to your account; invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — channel bindings are unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — channel bindings are not enabled yet (the message gateway deploy is pending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "bind-chat" } }, "/v1/workflows/{id}/bindings/{channel}/{sender_id}": { "delete": { "operationId": "delete-v1-workflows-id-bindings-channel-sender-id", "tags": [ "Bots" ], "summary": "Unbind a chat from a bot", "description": "Only this bot’s own bindings; a chat bound elsewhere is 404 binding_not_found.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved workflow id (a bot you own)" }, { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sender_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Released", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this account (foreign and missing ids answer alike); binding_not_found — that chat is not bound to this bot; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "unbind_failed — the chat could not be released", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — channel bindings are unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — channel bindings are not enabled yet (the message gateway deploy is pending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "unbind-chat" } }, "/v1/bot-groups": { "get": { "operationId": "get-v1-bot-groups", "tags": [ "Bots" ], "summary": "Your bot groups", "description": "Named sets of 2 to 6 of your saved bots; `message_bot to=group:` fans out to the members.", "security": [ { "ozkBearer": [] } ], "responses": { "200": { "description": "Groups Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "members": { "type": "array", "items": { "type": "string" }, "description": "Saved-bot ids, 2 to 6" }, "created_at": { "type": "integer", "description": "Unix seconds" }, "updated_at": { "type": "integer", "description": "Unix seconds" } }, "required": [ "id", "name", "members" ] } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-bot-groups" }, "post": { "operationId": "post-v1-bot-groups", "tags": [ "Bots" ], "summary": "Create a bot group", "description": "Members must all be your own saved bots, without repeats.", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "1-40 letters, digits, \"_\", \".\" or \"-\"; unique per account" }, "members": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 6, "description": "Your saved-bot ids" } }, "required": [ "name", "members" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "members": { "type": "array", "items": { "type": "string" }, "description": "Saved-bot ids, 2 to 6" }, "created_at": { "type": "integer", "description": "Unix seconds" }, "updated_at": { "type": "integer", "description": "Unix seconds" } }, "required": [ "id", "name", "members" ] } } } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "name_taken — you already have a group with that name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_name or invalid_members — the name is not 1-40 letters, digits, \"_\", \".\" or \"-\", or the members are not 2 to 6 distinct bots of yours", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — bot groups are not enabled yet (migration 0139 is pending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "create-bot-group" } }, "/v1/bot-groups/{id}": { "put": { "operationId": "put-v1-bot-groups-id", "tags": [ "Bots" ], "summary": "Replace a bot group", "description": "Same body and checks as create; the group must be yours.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "1-40 letters, digits, \"_\", \".\" or \"-\"; unique per account" }, "members": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 6, "description": "Your saved-bot ids" } }, "required": [ "name", "members" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "members": { "type": "array", "items": { "type": "string" }, "description": "Saved-bot ids, 2 to 6" }, "created_at": { "type": "integer", "description": "Unix seconds" }, "updated_at": { "type": "integer", "description": "Unix seconds" } }, "required": [ "id", "name", "members" ] } } } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "group_not_found — no bot group with that id for this account; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "name_taken — you already have a group with that name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_name or invalid_members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — bot groups are not enabled yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "replace-bot-group" }, "delete": { "operationId": "delete-v1-bot-groups-id", "tags": [ "Bots" ], "summary": "Delete a bot group", "description": "The member bots are untouched.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "group_not_found — no bot group with that id for this account; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — bot groups are not enabled yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "delete-bot-group" } }, "/v1/bot-groups/{id}/thread": { "get": { "operationId": "get-v1-bot-groups-id-thread", "tags": [ "Bots" ], "summary": "A bot group’s shared thread", "description": "Messages sent to the group, oldest first. Read-only.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thread Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "from_name": { "type": "string" }, "text": { "type": "string" }, "ts": { "type": "integer" }, "hops": { "type": "integer" }, "group": { "type": "string" } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "group_not_found — no bot group with that id for this account; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-bot-group-thread" } }, "/v1/channels": { "get": { "operationId": "get-v1-channels", "tags": [ "Bots" ], "summary": "Your paired channels", "description": "The chats you paired per channel (Telegram, WhatsApp, Discord, Teams); `targets[].sender_id` is what `POST /v1/workflows/{id}/bindings` takes.", "security": [ { "ozkBearer": [] } ], "responses": { "200": { "description": "Paired devices per channel Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "object", "additionalProperties": { "type": "object", "properties": { "connected": { "type": "boolean" }, "targets": { "type": "array", "items": { "type": "object", "properties": { "sender_id": { "type": "string" }, "sender_name": { "type": [ "string", "null" ] } } } } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-channels" } }, "/v1/channels/pair": { "post": { "operationId": "post-v1-channels-pair", "tags": [ "Bots" ], "summary": "Mint a pairing code", "description": "Send the code to the channel’s bot from the device to pair it (valid for 10 minutes); the device then appears in `GET /v1/channels`.", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "telegram", "whatsapp", "discord", "teams" ] } }, "required": [ "channel" ] } } } }, "responses": { "200": { "description": "Pairing code Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "expires_at": { "type": [ "integer", "null" ], "description": "Epoch milliseconds" } }, "required": [ "code" ] } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — channel must be telegram, whatsapp, discord, or teams", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — pairing is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the message gateway is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "create-pairing-code" } }, "/v1/companies": { "get": { "operationId": "get-v1-companies", "tags": [ "Companies" ], "summary": "List your companies", "description": "The switcher: one row per applied campus with its mode, status, building count and the number of approvals waiting at its door.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "Your companies Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] }, "status": { "type": "string", "enum": [ "applied", "running", "stopped" ] }, "buildings": { "type": "integer" }, "local": { "type": "integer", "description": "Buildings with `location: local`" }, "connected": { "type": "integer", "description": "Local buildings whose node reported in the last five minutes" }, "pending": { "type": "integer", "description": "Approvals waiting at the door" }, "applied_at": { "type": "string" } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-companies" } }, "/v1/companies/{campus}/apply": { "post": { "operationId": "post-v1-companies-campus-apply", "tags": [ "Companies" ], "summary": "Apply a company", "description": "Compiles the saved campus, building and office documents (kinds `campus`, `building`, `workflow` …; save them with POST /v1/workflows?kind=) and stores the plan. Idempotent by name: inline offices are saved as `//` workflows, removed ones are deleted by name. Does not start the clock: POST …/start.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "What was applied Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campus": { "type": "string" }, "buildings": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "location": { "type": "string", "enum": [ "cloud", "local" ] }, "offices": { "type": "integer" } } } }, "workflows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "action": { "type": "string", "enum": [ "created", "updated" ] } } } }, "schedules": { "type": "array", "items": { "type": "object", "properties": { "building": { "type": "string" }, "cron": { "type": "string" }, "office": { "type": "string" }, "status": { "type": "string", "enum": [ "pending" ] } } } }, "local": { "type": "array", "items": { "type": "object", "properties": { "building": { "type": "string" }, "slice_sha": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "the documents do not compile (the message names the document path and why); nothing was stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "apply-company" } }, "/v1/companies/{campus}/layout": { "get": { "operationId": "get-v1-companies-campus-layout", "tags": [ "Companies" ], "summary": "The compiled company", "description": "Where things stand: buildings (with `location`, `pipeline`, and `connected` for a local building) and their offices. Positions come from document order only, so a re-apply never reshuffles.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The compiled tree Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campus": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ], "description": "The live mode (a PUT …/mode wins over the document)" }, "manager": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "user", "team" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ] }, "workspace": { "type": "object", "properties": { "company": { "type": [ "string", "null" ] } } } }, "required": [ "slug", "name", "mode" ] }, "buildings": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "campus": { "type": "string" }, "order": { "type": "integer", "description": "Document order: the plot it stands on" }, "location": { "type": "string", "enum": [ "cloud", "local" ] }, "project": { "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] }, "manager": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "user", "team" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ] }, "workspace": { "type": "object", "properties": { "project": { "type": [ "string", "null" ] }, "team": { "type": [ "string", "null" ] } } }, "policy": { "type": "object", "properties": { "rubric": { "type": "string" }, "gates": { "type": "object", "additionalProperties": { "type": "string" } }, "budget": { "type": "object", "properties": { "day_usd": { "type": [ "number", "null" ] }, "item_usd": { "type": [ "number", "null" ] } } } } }, "floors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "team": { "type": [ "string", "null" ] }, "offices": { "type": "array", "items": { "type": "string" } } } } }, "intake": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pipeline": { "type": "array", "items": { "type": "object", "required": [ "id", "kind" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "office", "parallel", "sequential", "gate", "then" ] }, "offices": { "type": "array", "items": { "type": "string" }, "description": "office, parallel, sequential" }, "retry": { "type": [ "string", "null" ] }, "skip": { "type": [ "string", "null" ] }, "gate": { "type": "string", "description": "gate" }, "building": { "type": "string", "description": "then" } } } }, "connected": { "type": "boolean", "description": "A cloud building is always connected" } }, "required": [ "slug", "location", "pipeline", "connected" ] }, "description": "In document order" }, "offices": { "type": "array", "items": { "type": "object", "properties": { "building": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "floor": { "type": "string" }, "order": { "type": "integer" }, "source": { "type": "string", "enum": [ "ref", "inline", "runner" ] } }, "required": [ "building", "slug", "floor", "order" ] } } }, "required": [ "campus", "buildings", "offices" ] } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-company-layout" } }, "/v1/companies/{campus}/snapshot": { "get": { "operationId": "get-v1-companies-campus-snapshot", "tags": [ "Companies" ], "summary": "The company now", "description": "State with `head_seq`: each office idle, running, waiting or offline, the active items, the line at the door, spend today and items shipped in 7 days. Fold GET …/events over it, dropping `seq <= head_seq`.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The snapshot Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "head_seq": { "type": "integer", "description": "Drop events with seq <= head_seq when folding them over this snapshot. Read before the state, so a later event may already show in it: fold idempotently" }, "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] }, "status": { "type": "string", "enum": [ "applied", "running", "stopped" ] }, "buildings": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "location": { "type": "string", "enum": [ "cloud", "local" ] }, "connected": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] }, "active": { "type": "integer" } } } }, "offices": { "type": "array", "items": { "type": "object", "properties": { "building": { "type": "string" }, "office": { "type": "string" }, "state": { "type": "string", "enum": [ "idle", "running", "waiting", "offline" ] }, "item_id": { "type": [ "string", "null" ] } } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "campus": { "type": "string" }, "building": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "source": { "type": "string", "enum": [ "api", "bot", "schedule", "then", "node" ] }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ], "description": "The standard’s tier word (`T2`, `V1`); null until set" }, "step": { "type": "string", "description": "`intake`, a step id of the building’s pipeline, `done` or `parked`" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "done", "failed", "parked" ] }, "parked_reason": { "type": [ "string", "null" ] }, "paused": { "type": "integer", "enum": [ 0, 1 ] }, "cost_usd": { "type": "number" }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "description": "The item without its bodies (`body`, `last_output`, `steer`): GET …/items/{id} has them" }, "description": "Active and parked items, and what finished in the last day: priority first, then newest" }, "queue": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "item_id": { "type": "string" }, "building": { "type": "string" }, "step": { "type": "string" }, "gate": { "type": "string" }, "tier": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "payload_json": { "type": "string" }, "execution_id": { "type": [ "string", "null" ], "description": "For a `tool_permission` gate raised inside an office: the paused execution" }, "requested_at": { "type": "string" }, "expires_at": { "type": "string" }, "decided_at": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ], "description": "`auto`, `timeout`, `user:`, `team:` or `node`" }, "note": { "type": [ "string", "null" ] } } }, "description": "The line at the door: pending approvals, oldest first" }, "truncated": { "type": "boolean", "description": "true when a cap cut a list: `items` holds the newest 500, `queue` the oldest 200 pending approvals" }, "spend_today_usd": { "type": "number" }, "shipped_7d": { "type": "integer" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-company-snapshot" } }, "/v1/companies/{campus}/events": { "get": { "operationId": "get-v1-companies-campus-events", "tags": [ "Companies" ], "summary": "The company’s event log", "description": "A JSON page after `since` (a seq), or, with `Accept: text/event-stream` or `?stream=1`, a live SSE feed: `id: `, `event: `, `data: `, polled every 2 s, a `: hb` comment every 15 s of quiet, and resumable with `Last-Event-ID`. A feed that ends on a failure sends one `event: error` first.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "since", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Rows after this seq. On the live feed `Last-Event-ID` wins when both are sent" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "JSON page only: at most this many rows (the service default is 200)" }, { "name": "stream", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "description": "Live SSE feed (the same as `Accept: text/event-stream`)" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "Events after `since`, oldest first Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON. With `Accept: text/event-stream` or `?stream=1`: an SSE stream of one event row per frame.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "description": "Per company, dense, ascending: fold events in seq order" }, "campus": { "type": "string" }, "building": { "type": [ "string", "null" ] }, "item_id": { "type": [ "string", "null" ] }, "office": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "item.created", "step.enter", "step.exit", "run.start", "run.end", "desk.progress", "handoff", "approval.requested", "approval.decided", "item.parked", "item.resumed", "item.done", "budget.warn", "budget.stop", "config.changed", "building.connected", "item.then", "error" ] }, "data": { "type": "object", "additionalProperties": true, "description": "References only, never bodies; its keys by `type` are in `x-data-by-type`. A reader ignores keys it does not know", "x-data-by-type": { "item.created": { "type": "object", "properties": { "source": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ] }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "title" ] }, "step.enter": { "type": "object", "properties": { "step": { "type": "string" }, "attempt": { "type": "integer" } }, "required": [ "step" ] }, "step.exit": { "type": "object", "properties": { "step": { "type": "string" }, "outcome": { "type": "string" } }, "required": [ "step" ] }, "run.start": { "type": "object", "properties": { "step": { "type": "string" }, "office": { "type": "string" }, "run_id": { "type": "string" }, "execution_id": { "type": "string" } }, "required": [ "office" ] }, "run.end": { "type": "object", "properties": { "step": { "type": "string" }, "office": { "type": "string" }, "run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "failed", "cancelled" ] }, "cost_usd": { "type": "number" }, "execution_id": { "type": [ "string", "null" ] }, "settled": { "type": "boolean", "description": "A late cost for a run that had already ended: only the cost moves" }, "item_cost_usd": { "type": "number" } }, "required": [ "office", "status" ] }, "approval.requested": { "type": "object", "properties": { "approval_id": { "type": "string" }, "step": { "type": "string" }, "gate": { "type": "string" }, "tier": { "type": [ "string", "null" ] }, "payload": { "type": "object", "additionalProperties": true }, "requested_at": { "type": "string" }, "expires_at": { "type": "string" }, "execution_id": { "type": "string" } }, "required": [ "approval_id", "gate" ] }, "approval.decided": { "type": "object", "properties": { "approval_id": { "type": "string" }, "gate": { "type": "string" }, "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "expired" ] }, "by": { "type": [ "string", "null" ] }, "note": { "type": "string" }, "execution_id": { "type": "string" } }, "required": [ "approval_id", "status" ] }, "item.parked": { "type": "object", "properties": { "reason": { "type": "string" }, "step": { "type": "string" }, "restart": { "type": "boolean", "description": "The visit was abandoned: a resume starts the step afresh" }, "office": { "type": "string" }, "execution_id": { "type": "string" } }, "required": [ "reason" ] }, "item.resumed": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "resume", "retry" ] }, "step": { "type": "string" }, "attempt": { "type": "integer" }, "from": { "type": [ "string", "null" ] } }, "required": [ "action" ] }, "item.done": { "type": "object", "properties": { "cost_usd": { "type": "number" } } }, "item.then": { "type": "object", "properties": { "building": { "type": "string", "description": "The building the item hands on to" }, "to": { "type": "string", "description": "The same as `building` (kept for older readers)" }, "child": { "type": [ "string", "null" ], "description": "The child item; null when a local node takes it" }, "child_id": { "type": "string", "description": "The same as `child` (kept for older readers)" }, "local": { "type": "boolean" } }, "required": [ "building" ] }, "handoff": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "child_id": { "type": "string" } } }, "config.changed": { "type": "object", "properties": { "change": { "type": "string", "enum": [ "apply" ], "description": "A new plan: re-read layout and snapshot" }, "version": { "type": "integer" }, "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] }, "previous": { "type": "string" }, "buildings": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] }, "description": "Each building’s mode after a mode switch" }, "status": { "type": "string", "enum": [ "running", "stopped" ] }, "item_id": { "type": "string" }, "paused": { "type": "boolean" }, "steer": { "type": "boolean" } } }, "building.connected": { "type": "object", "properties": { "node": { "type": "string" }, "connected": { "type": "boolean" } } }, "budget.warn": { "type": "object", "properties": { "scope": { "type": "string" }, "cost_usd": { "type": "number" }, "limit_usd": { "type": "number" }, "pct": { "type": "integer" } } }, "budget.stop": { "type": "object", "properties": { "scope": { "type": "string" }, "cost_usd": { "type": "number" }, "limit_usd": { "type": "number" } } }, "desk.progress": { "type": "object", "additionalProperties": true }, "error": { "type": "object", "additionalProperties": true } } }, "at": { "type": "string" } }, "required": [ "seq", "campus", "type", "data", "at" ] } }, "head_seq": { "type": "integer" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — since or limit is not a whole number in range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-company-events" }, "post": { "operationId": "post-v1-companies-campus-events", "tags": [ "Companies" ], "summary": "Report events from a local building", "description": "A local building’s node (`factoryd`) mirrors its own events up with the owner’s key; the rows join the log in order. Only a building with `location: local` that belongs to the company is accepted.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "building": { "type": "string" }, "item_id": { "type": "string" }, "office": { "type": "string" }, "type": { "type": "string", "enum": [ "item.created", "step.enter", "step.exit", "run.start", "run.end", "desk.progress", "handoff", "approval.requested", "approval.decided", "item.parked", "item.resumed", "item.done", "budget.warn", "budget.stop", "config.changed", "building.connected", "item.then", "error" ] }, "data": { "type": "object", "additionalProperties": true }, "at": { "type": "string", "description": "When it happened on the node (ISO 8601); defaults to receipt" } }, "required": [ "building", "type" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "events" ] } }, "text/yaml": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "building": { "type": "string" }, "item_id": { "type": "string" }, "office": { "type": "string" }, "type": { "type": "string", "enum": [ "item.created", "step.enter", "step.exit", "run.start", "run.end", "desk.progress", "handoff", "approval.requested", "approval.decided", "item.parked", "item.resumed", "item.done", "budget.warn", "budget.stop", "config.changed", "building.connected", "item.then", "error" ] }, "data": { "type": "object", "additionalProperties": true }, "at": { "type": "string", "description": "When it happened on the node (ISO 8601); defaults to receipt" } }, "required": [ "building", "type" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "events" ] } } } }, "responses": { "200": { "description": "How many were taken Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "integer" }, "head_seq": { "type": "integer" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "report-company-events" } }, "/v1/companies/{campus}/buildings/{building}/slice": { "get": { "operationId": "get-v1-companies-campus-buildings-building-slice", "tags": [ "Companies" ], "summary": "A local building’s slice", "description": "The compiled pipeline, policy, project and office ids of one `location: local` building: what its node pulls to run it.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "building", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The building’s slug" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The slice Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); or no such building in this company; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-building-slice" } }, "/v1/companies/{campus}/items/{id}": { "get": { "operationId": "get-v1-companies-campus-items-id", "tags": [ "Companies" ], "summary": "One item in full", "description": "The item with its bodies (`body`, `last_output`, `steer` — the snapshot leaves them out), every office run, every approval and its own events. A foreign or unknown id is 404.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Item id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The item Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "campus": { "type": "string" }, "building": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "source": { "type": "string", "enum": [ "api", "bot", "schedule", "then", "node" ] }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ], "description": "The standard’s tier word (`T2`, `V1`); null until set" }, "step": { "type": "string", "description": "`intake`, a step id of the building’s pipeline, `done` or `parked`" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "done", "failed", "parked" ] }, "parked_reason": { "type": [ "string", "null" ] }, "paused": { "type": "integer", "enum": [ 0, 1 ] }, "steer": { "type": [ "string", "null" ] }, "last_output": { "type": [ "string", "null" ], "description": "The previous step’s output, the next office’s `{input}`" }, "cost_usd": { "type": "number" }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "item_id": { "type": "string" }, "building": { "type": "string" }, "step": { "type": "string" }, "office": { "type": "string" }, "kind": { "type": "string", "enum": [ "platform", "node" ] }, "ref": { "type": [ "string", "null" ], "description": "The execution id of a platform run" }, "status": { "type": "string", "enum": [ "running", "ok", "failed", "cancelled" ] }, "cost_usd": { "type": "number" }, "error": { "type": [ "string", "null" ] }, "started_at": { "type": "string" }, "ended_at": { "type": [ "string", "null" ] } } }, "description": "Every office run, oldest first" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "item_id": { "type": "string" }, "building": { "type": "string" }, "step": { "type": "string" }, "gate": { "type": "string" }, "tier": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "payload_json": { "type": "string" }, "execution_id": { "type": [ "string", "null" ], "description": "For a `tool_permission` gate raised inside an office: the paused execution" }, "requested_at": { "type": "string" }, "expires_at": { "type": "string" }, "decided_at": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ], "description": "`auto`, `timeout`, `user:`, `team:` or `node`" }, "note": { "type": [ "string", "null" ] } } }, "description": "Every approval, oldest first" }, "history": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "description": "Per company, dense, ascending: fold events in seq order" }, "campus": { "type": "string" }, "building": { "type": [ "string", "null" ] }, "item_id": { "type": [ "string", "null" ] }, "office": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "item.created", "step.enter", "step.exit", "run.start", "run.end", "desk.progress", "handoff", "approval.requested", "approval.decided", "item.parked", "item.resumed", "item.done", "budget.warn", "budget.stop", "config.changed", "building.connected", "item.then", "error" ] }, "data": { "type": "object", "additionalProperties": true, "description": "References only, never bodies; its keys by `type` are in `x-data-by-type`. A reader ignores keys it does not know", "x-data-by-type": { "item.created": { "type": "object", "properties": { "source": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ] }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "title" ] }, "step.enter": { "type": "object", "properties": { "step": { "type": "string" }, "attempt": { "type": "integer" } }, "required": [ "step" ] }, "step.exit": { "type": "object", "properties": { "step": { "type": "string" }, "outcome": { "type": "string" } }, "required": [ "step" ] }, "run.start": { "type": "object", "properties": { "step": { "type": "string" }, "office": { "type": "string" }, "run_id": { "type": "string" }, "execution_id": { "type": "string" } }, "required": [ "office" ] }, "run.end": { "type": "object", "properties": { "step": { "type": "string" }, "office": { "type": "string" }, "run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "failed", "cancelled" ] }, "cost_usd": { "type": "number" }, "execution_id": { "type": [ "string", "null" ] }, "settled": { "type": "boolean", "description": "A late cost for a run that had already ended: only the cost moves" }, "item_cost_usd": { "type": "number" } }, "required": [ "office", "status" ] }, "approval.requested": { "type": "object", "properties": { "approval_id": { "type": "string" }, "step": { "type": "string" }, "gate": { "type": "string" }, "tier": { "type": [ "string", "null" ] }, "payload": { "type": "object", "additionalProperties": true }, "requested_at": { "type": "string" }, "expires_at": { "type": "string" }, "execution_id": { "type": "string" } }, "required": [ "approval_id", "gate" ] }, "approval.decided": { "type": "object", "properties": { "approval_id": { "type": "string" }, "gate": { "type": "string" }, "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "expired" ] }, "by": { "type": [ "string", "null" ] }, "note": { "type": "string" }, "execution_id": { "type": "string" } }, "required": [ "approval_id", "status" ] }, "item.parked": { "type": "object", "properties": { "reason": { "type": "string" }, "step": { "type": "string" }, "restart": { "type": "boolean", "description": "The visit was abandoned: a resume starts the step afresh" }, "office": { "type": "string" }, "execution_id": { "type": "string" } }, "required": [ "reason" ] }, "item.resumed": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "resume", "retry" ] }, "step": { "type": "string" }, "attempt": { "type": "integer" }, "from": { "type": [ "string", "null" ] } }, "required": [ "action" ] }, "item.done": { "type": "object", "properties": { "cost_usd": { "type": "number" } } }, "item.then": { "type": "object", "properties": { "building": { "type": "string", "description": "The building the item hands on to" }, "to": { "type": "string", "description": "The same as `building` (kept for older readers)" }, "child": { "type": [ "string", "null" ], "description": "The child item; null when a local node takes it" }, "child_id": { "type": "string", "description": "The same as `child` (kept for older readers)" }, "local": { "type": "boolean" } }, "required": [ "building" ] }, "handoff": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "child_id": { "type": "string" } } }, "config.changed": { "type": "object", "properties": { "change": { "type": "string", "enum": [ "apply" ], "description": "A new plan: re-read layout and snapshot" }, "version": { "type": "integer" }, "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] }, "previous": { "type": "string" }, "buildings": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] }, "description": "Each building’s mode after a mode switch" }, "status": { "type": "string", "enum": [ "running", "stopped" ] }, "item_id": { "type": "string" }, "paused": { "type": "boolean" }, "steer": { "type": "boolean" } } }, "building.connected": { "type": "object", "properties": { "node": { "type": "string" }, "connected": { "type": "boolean" } } }, "budget.warn": { "type": "object", "properties": { "scope": { "type": "string" }, "cost_usd": { "type": "number" }, "limit_usd": { "type": "number" }, "pct": { "type": "integer" } } }, "budget.stop": { "type": "object", "properties": { "scope": { "type": "string" }, "cost_usd": { "type": "number" }, "limit_usd": { "type": "number" } } }, "desk.progress": { "type": "object", "additionalProperties": true }, "error": { "type": "object", "additionalProperties": true } } }, "at": { "type": "string" } }, "required": [ "seq", "campus", "type", "data", "at" ] }, "description": "The item’s own events, oldest first (the newest 500)" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); or no item with that id in this company; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-company-item" } }, "/v1/companies/{campus}/items": { "post": { "operationId": "post-v1-companies-campus-items", "tags": [ "Companies" ], "summary": "Put an item into a building", "description": "Creates an item at the building’s intake. A cloud building walks it office to office; a local building’s node picks it up. Answers 201 with the item.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "building": { "type": "string", "description": "The building slug the item enters (its intake)" }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "body": { "type": "string", "maxLength": 65536 }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "priority": { "type": "integer" }, "tier": { "type": "string", "maxLength": 32, "description": "The standard’s tier word; unset means the standard’s default" } }, "required": [ "building", "title" ] } }, "text/yaml": { "schema": { "type": "object", "properties": { "building": { "type": "string", "description": "The building slug the item enters (its intake)" }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "body": { "type": "string", "maxLength": 65536 }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "priority": { "type": "integer" }, "tier": { "type": "string", "maxLength": 32, "description": "The standard’s tier word; unset means the standard’s default" } }, "required": [ "building", "title" ] } } } }, "responses": { "201": { "description": "The item, at `step: intake`", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "campus": { "type": "string" }, "building": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "source": { "type": "string", "enum": [ "api", "bot", "schedule", "then", "node" ] }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ], "description": "The standard’s tier word (`T2`, `V1`); null until set" }, "step": { "type": "string", "description": "`intake`, a step id of the building’s pipeline, `done` or `parked`" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "done", "failed", "parked" ] }, "parked_reason": { "type": [ "string", "null" ] }, "paused": { "type": "integer", "enum": [ 0, 1 ] }, "steer": { "type": [ "string", "null" ] }, "last_output": { "type": [ "string", "null" ], "description": "The previous step’s output, the next office’s `{input}`" }, "cost_usd": { "type": "number" }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); or no such building in this company; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "create-company-item" } }, "/v1/companies/{campus}/items/{id}/pause": { "post": { "operationId": "post-v1-companies-campus-items-id-pause", "tags": [ "Companies" ], "summary": "Pause an item", "description": "The item keeps its step and stops being walked until it is resumed. Answers the item as it is now.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Item id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The item Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "campus": { "type": "string" }, "building": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "source": { "type": "string", "enum": [ "api", "bot", "schedule", "then", "node" ] }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ], "description": "The standard’s tier word (`T2`, `V1`); null until set" }, "step": { "type": "string", "description": "`intake`, a step id of the building’s pipeline, `done` or `parked`" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "done", "failed", "parked" ] }, "parked_reason": { "type": [ "string", "null" ] }, "paused": { "type": "integer", "enum": [ 0, 1 ] }, "steer": { "type": [ "string", "null" ] }, "last_output": { "type": [ "string", "null" ], "description": "The previous step’s output, the next office’s `{input}`" }, "cost_usd": { "type": "number" }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); or no item with that id in this company; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the item is in a state this action does not apply to (the code and message say why); nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "pause-company-item" } }, "/v1/companies/{campus}/items/{id}/resume": { "post": { "operationId": "post-v1-companies-campus-items-id-resume", "tags": [ "Companies" ], "summary": "Resume an item", "description": "Resumes a paused or parked item at the step it stopped on (a parked item starts a fresh visit). Answers the item as it is now.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Item id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The item Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "campus": { "type": "string" }, "building": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "source": { "type": "string", "enum": [ "api", "bot", "schedule", "then", "node" ] }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ], "description": "The standard’s tier word (`T2`, `V1`); null until set" }, "step": { "type": "string", "description": "`intake`, a step id of the building’s pipeline, `done` or `parked`" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "done", "failed", "parked" ] }, "parked_reason": { "type": [ "string", "null" ] }, "paused": { "type": "integer", "enum": [ 0, 1 ] }, "steer": { "type": [ "string", "null" ] }, "last_output": { "type": [ "string", "null" ], "description": "The previous step’s output, the next office’s `{input}`" }, "cost_usd": { "type": "number" }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); or no item with that id in this company; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the item is in a state this action does not apply to (the code and message say why); nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "resume-company-item" } }, "/v1/companies/{campus}/items/{id}/retry": { "post": { "operationId": "post-v1-companies-campus-items-id-retry", "tags": [ "Companies" ], "summary": "Retry an item’s step", "description": "Starts the step again as the next attempt (`attempt + 1`), or at the pipeline’s retry target when it has one. Answers the item as it is now.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Item id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The item Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "campus": { "type": "string" }, "building": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "source": { "type": "string", "enum": [ "api", "bot", "schedule", "then", "node" ] }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ], "description": "The standard’s tier word (`T2`, `V1`); null until set" }, "step": { "type": "string", "description": "`intake`, a step id of the building’s pipeline, `done` or `parked`" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "done", "failed", "parked" ] }, "parked_reason": { "type": [ "string", "null" ] }, "paused": { "type": "integer", "enum": [ 0, 1 ] }, "steer": { "type": [ "string", "null" ] }, "last_output": { "type": [ "string", "null" ], "description": "The previous step’s output, the next office’s `{input}`" }, "cost_usd": { "type": "number" }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); or no item with that id in this company; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the item is in a state this action does not apply to (the code and message say why); nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "retry-company-item" } }, "/v1/companies/{campus}/items/{id}/cancel": { "post": { "operationId": "post-v1-companies-campus-items-id-cancel", "tags": [ "Companies" ], "summary": "Cancel an item", "description": "The item ends `failed` with `parked_reason: cancelled`; its running office runs are not interrupted. Answers the item as it is now.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Item id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The item Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "campus": { "type": "string" }, "building": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "source": { "type": "string", "enum": [ "api", "bot", "schedule", "then", "node" ] }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ], "description": "The standard’s tier word (`T2`, `V1`); null until set" }, "step": { "type": "string", "description": "`intake`, a step id of the building’s pipeline, `done` or `parked`" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "done", "failed", "parked" ] }, "parked_reason": { "type": [ "string", "null" ] }, "paused": { "type": "integer", "enum": [ 0, 1 ] }, "steer": { "type": [ "string", "null" ] }, "last_output": { "type": [ "string", "null" ], "description": "The previous step’s output, the next office’s `{input}`" }, "cost_usd": { "type": "number" }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); or no item with that id in this company; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the item is in a state this action does not apply to (the code and message say why); nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "cancel-company-item" } }, "/v1/companies/{campus}/items/{id}/steer": { "post": { "operationId": "post-v1-companies-campus-items-id-steer", "tags": [ "Companies" ], "summary": "Steer an item", "description": "Adds a note the next office run receives once, appended to its input; the note is cleared after that run starts. Answers the item as it is now.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Item id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 65536 } }, "required": [ "text" ] } }, "text/yaml": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 65536 } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "The item Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "campus": { "type": "string" }, "building": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "type": "string", "enum": [ "feature", "bugfix", "docs", "research", "content", "task" ] }, "source": { "type": "string", "enum": [ "api", "bot", "schedule", "then", "node" ] }, "priority": { "type": "integer" }, "tier": { "type": [ "string", "null" ], "description": "The standard’s tier word (`T2`, `V1`); null until set" }, "step": { "type": "string", "description": "`intake`, a step id of the building’s pipeline, `done` or `parked`" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "done", "failed", "parked" ] }, "parked_reason": { "type": [ "string", "null" ] }, "paused": { "type": "integer", "enum": [ 0, 1 ] }, "steer": { "type": [ "string", "null" ] }, "last_output": { "type": [ "string", "null" ], "description": "The previous step’s output, the next office’s `{input}`" }, "cost_usd": { "type": "number" }, "parent_item_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); or no item with that id in this company; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the item is in a state this action does not apply to (the code and message say why); nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "steer-company-item" } }, "/v1/companies/{campus}/approvals": { "get": { "operationId": "get-v1-companies-campus-approvals", "tags": [ "Companies" ], "summary": "The door: approvals", "description": "The gates waiting on a person, and tool permissions an office run asked for. `status` filters; without it the service’s default list (the pending line) is returned.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "description": "Only approvals in this state" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "Approvals Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "item_id": { "type": "string" }, "building": { "type": "string" }, "step": { "type": "string" }, "gate": { "type": "string" }, "tier": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "payload_json": { "type": "string" }, "execution_id": { "type": [ "string", "null" ], "description": "For a `tool_permission` gate raised inside an office: the paused execution" }, "requested_at": { "type": "string" }, "expires_at": { "type": "string" }, "decided_at": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ], "description": "`auto`, `timeout`, `user:`, `team:` or `node`" }, "note": { "type": [ "string", "null" ] } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-company-approvals" } }, "/v1/companies/{campus}/approvals/{ap}": { "post": { "operationId": "post-v1-companies-campus-approvals-ap", "tags": [ "Companies" ], "summary": "Decide an approval", "description": "Approve or reject a pending gate. Approving a tool permission also resumes the execution that paused for it, once; that part never fails the decision (see `continue_error`). A reject leaves the execution paused. An approval that is not pending, or not yours to decide, is refused.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "ap", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Approval id (from the door: GET …/approvals)" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "note": { "type": "string", "maxLength": 65536 } }, "required": [ "decision" ] } }, "text/yaml": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "note": { "type": "string", "maxLength": 65536 } }, "required": [ "decision" ] } } } }, "responses": { "200": { "description": "The decision as recorded Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string" }, "item_id": { "type": "string" }, "building": { "type": "string" }, "step": { "type": "string" }, "gate": { "type": "string" }, "tier": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "payload_json": { "type": "string" }, "execution_id": { "type": [ "string", "null" ], "description": "For a `tool_permission` gate raised inside an office: the paused execution" }, "requested_at": { "type": "string" }, "expires_at": { "type": "string" }, "decided_at": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ], "description": "`auto`, `timeout`, `user:`, `team:` or `node`" }, "note": { "type": [ "string", "null" ] } } }, "execution_id": { "type": "string", "description": "Present for a tool permission: the execution that paused for it" }, "continued": { "type": "boolean", "description": "Present with `execution_id`: true when an approve resumed that execution. A reject leaves it paused (false, no error)" }, "continue_error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "not_paused", "session_expired", "execution_not_found", "continue_failed" ] }, "message": { "type": "string" } }, "description": "The approve was recorded but the execution could not be resumed; answer it by hand with POST /v1/executions/{id}/continue" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); or no approval with that id in this company; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the approval was already decided or expired, or is not yours to decide; nothing changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "decide-company-approval" } }, "/v1/companies/{campus}/mode": { "put": { "operationId": "put-v1-companies-campus-mode", "tags": [ "Companies" ], "summary": "Set the company mode", "description": "The live switch: `supervised` asks at every gate, `tiered` asks by the standard’s tiers, `autonomous` asks only where a building’s policy says `require`. Overrides the campus and every building (a building’s documented mode included) and survives every apply; setting the campus’s documented mode clears it, so each building reads its documented mode again. Takes effect on the next tick and is logged as `config.changed`.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] } }, "required": [ "mode" ] } }, "text/yaml": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "The mode now set Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "supervised", "tiered", "autonomous" ] } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "set-company-mode" } }, "/v1/companies/{campus}/start": { "post": { "operationId": "post-v1-companies-campus-start", "tags": [ "Companies" ], "summary": "Start the company’s clock", "description": "Arms the campus clock: its items are walked until the clock is stopped. Idempotent.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The clock is running Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "running" ] } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "start-company" } }, "/v1/companies/{campus}/stop": { "post": { "operationId": "post-v1-companies-campus-stop", "tags": [ "Companies" ], "summary": "Stop the company’s clock", "description": "Disarms the campus clock; items keep their step and wait. Idempotent.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "The clock is stopped Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "stopped" ] } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON or YAML; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field failed validation; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "stop-company" } }, "/v1/companies/{campus}": { "delete": { "operationId": "delete-v1-companies-campus", "tags": [ "Companies" ], "summary": "Delete a company", "description": "Deletes a stopped or never-started company and every row of it — buildings, offices, items, runs, approvals, the event log and the manifest — at once. A running company is refused: POST …/stop first. The saved campus, building and office documents stay, so POST …/apply brings the company back, empty.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "campus", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company’s slug (`plunge`), never a row id" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "company_not_found — no company with that slug for this account (a foreign slug answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "conflict — the company is running; stop it first. Nothing was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the company service is unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "not_enabled — the company service is not deployed on this tier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "delete-company" } }, "/v1/executions": { "get": { "operationId": "get-v1-executions", "tags": [ "Executions" ], "summary": "List your executions, newest first", "description": "Every run of this key’s user, whichever door started it (`source`: api, cli, mcp, studio, …).", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "source", "in": "query", "schema": { "type": "string" }, "description": "Only runs from this door" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "running", "completed", "failed", "cancelled" ] } }, { "name": "workflow_id", "in": "query", "schema": { "type": "string" }, "description": "Only runs of this saved workflow" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "Executions Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "executions": { "type": "array", "items": { "type": "object", "properties": { "execution_id": { "type": "string" }, "input": { "type": [ "string", "null" ] }, "workflow_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] } } } }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_status — status is not one of the four; invalid_format / invalid_json / invalid_yaml — unreadable body or unknown format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-executions" } }, "/v1/executions/{id}": { "get": { "operationId": "get-v1-executions-id", "tags": [ "Executions" ], "summary": "Status of an execution (poll this)", "description": "`status` is the run’s state; a run that finished its turn and waits on the user reads `needs_input` (a question) or `needs_approval` (a held action) with the `continuation` — answer it with POST …/continue.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" }, { "name": "on_behalf_of", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Read a run that was made on a customer’s behalf (POST /v1/execute with `on_behalf_of`): its output sits under `:cust:`. 1-128 characters of A-Z a-z 0-9 _ . - (no \"..\"); a bad value is 400 invalid_on_behalf_of. The run itself must still be yours. Honoured by the status, output and files reads only: continue, followup, steer, stream and conversation look under your own tenant." } ], "responses": { "200": { "description": "Execution status Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string" }, "status": { "type": "string", "description": "running | completed | incomplete | failed | cancelled, or needs_input / needs_approval when the run finished its turn and waits for the user (POST …/continue)" }, "error_message": { "type": [ "string", "null" ] }, "workflow_name": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "final_task_id": { "type": [ "string", "null" ] }, "continuation": { "type": [ "object", "null" ], "description": "Non-null when the run is paused awaiting the user", "properties": { "status": { "type": "string", "enum": [ "question", "needs_approval" ] }, "agent": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "pending_action": { "type": [ "object", "null" ], "description": "The held action: summary, price, and the permission class / tool when known" } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_on_behalf_of — not a valid customer id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "execution_not_found — no execution with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-execution" }, "delete": { "operationId": "delete-v1-executions-id", "tags": [ "Executions" ], "summary": "Delete an execution and its stored result", "description": "Removes the history row, the stored result and the follow-up thread. Idempotent per id: a second call is 404.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "Deleted Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "execution_not_found — no execution with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "delete-execution" } }, "/v1/executions/{id}/output": { "get": { "operationId": "get-v1-executions-id-output", "tags": [ "Executions" ], "summary": "The run’s final output (json, yaml, markdown or text)", "description": "The stored result of the final task. `format=text` is the bare content, `markdown` what the MCP plane renders, `json`/`yaml` the envelope.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" }, { "name": "on_behalf_of", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Read a run that was made on a customer’s behalf (POST /v1/execute with `on_behalf_of`): its output sits under `:cust:`. 1-128 characters of A-Z a-z 0-9 _ . - (no \"..\"); a bad value is 400 invalid_on_behalf_of. The run itself must still be yours. Honoured by the status, output and files reads only: continue, followup, steer, stream and conversation look under your own tenant." } ], "responses": { "200": { "description": "Output Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string" }, "status": { "type": "string", "description": "running | completed | incomplete | failed | cancelled, or needs_input / needs_approval when the run finished its turn and waits for the user (POST …/continue)" }, "content": { "type": "string" }, "final_task_id": { "type": [ "string", "null" ] }, "steps": { "type": "array", "description": "Every step of a multi-task run; the output is the final one’s", "items": { "type": "object", "properties": { "task_id": { "type": "string" }, "agent": { "type": [ "string", "null" ] }, "final": { "type": "boolean" } } } }, "continuation": { "type": [ "object", "null" ], "description": "Non-null when the run is paused awaiting the user", "properties": { "status": { "type": "string", "enum": [ "question", "needs_approval" ] }, "agent": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "pending_action": { "type": [ "object", "null" ], "description": "The held action: summary, price, and the permission class / tool when known" } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_on_behalf_of — not a valid customer id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "execution_not_found — no execution with that id for this key (a foreign id answers the same); not_ready — the run is still going, retry; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "execution_failed — the run failed; the message is its error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "result_expired — the run completed but its stored result is gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-execution-output" } }, "/v1/executions/{id}/conversation": { "get": { "operationId": "get-v1-executions-id-conversation", "tags": [ "Executions" ], "summary": "The follow-up and continue turns of a run", "description": "The `followups` thread: every user and agent turn added after the run by POST …/continue or …/followup.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" } ], "responses": { "200": { "description": "Thread Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "timestamp": { "type": "integer" } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "execution_not_found — no execution with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-execution-conversation" } }, "/v1/executions/{id}/files": { "get": { "operationId": "get-v1-executions-id-files", "tags": [ "Executions" ], "summary": "Files the run produced", "description": "Office/PDF deliverables the agent wrote during this run (spreadsheets, documents, decks), including those of a cloud-held relay run.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] }, "description": "Response format; overrides Accept (an unknown value is 400 invalid_format)" }, { "name": "on_behalf_of", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Read a run that was made on a customer’s behalf (POST /v1/execute with `on_behalf_of`): its output sits under `:cust:`. 1-128 characters of A-Z a-z 0-9 _ . - (no \"..\"); a bad value is 400 invalid_on_behalf_of. The run itself must still be yours. Honoured by the status, output and files reads only: continue, followup, steer, stream and conversation look under your own tenant." } ], "responses": { "200": { "description": "Files Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "size": { "type": "integer" }, "contentType": { "type": "string" }, "kind": { "type": "string" }, "ext": { "type": "string" }, "updatedAt": { "type": "string" } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_on_behalf_of — not a valid customer id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "execution_not_found — no execution with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-execution-files" } }, "/v1/executions/{id}/continue": { "post": { "operationId": "post-v1-executions-id-continue", "tags": [ "Executions" ], "summary": "Answer a paused run’s question or approve its held action", "description": "`answer` replies to a question (or denies / redirects an approval); `approve: true` approves the pending action with the stored token. `allow_scope` (approve only): `once` this call, `run` the tool for the rest of the run, `always` is the bot’s stored rule (set it with PUT /v1/workflows/{id}/permissions); any other value is `once`. Runs inline: up to ~30 s while an approved action executes.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string", "maxLength": 65536 }, "approve": { "type": "boolean" }, "allow_scope": { "type": "string", "enum": [ "once", "run", "always" ] }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "The agent’s reply Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string" }, "status": { "type": "string", "description": "running | completed | incomplete | failed | cancelled, or needs_input / needs_approval when the run finished its turn and waits for the user (POST …/continue)" }, "content": { "type": "string", "description": "The agent's reply" }, "continuation": { "type": [ "object", "null" ], "description": "Non-null when the run is paused awaiting the user", "properties": { "status": { "type": "string", "enum": [ "question", "needs_approval" ] }, "agent": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "pending_action": { "type": [ "object", "null" ], "description": "The held action: summary, price, and the permission class / tool when known" } } }, "conversation_recorded": { "type": "boolean", "description": "false when the turn ran but could not be saved to the thread (GET …/conversation lacks it); the reply is still returned" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "missing_answer — neither `answer` nor `approve: true`; invalid_params; invalid_format / invalid_json / invalid_yaml — unreadable body or unknown format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "execution_not_found — no execution with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "not_paused — the run already completed; use …/followup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "session_expired — no conversation session (expired, or not a conversational agent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "continue_failed — the agent could not continue; retry; upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "continue-execution" } }, "/v1/executions/{id}/followup": { "post": { "operationId": "post-v1-executions-id-followup", "tags": [ "Executions" ], "summary": "Message a run: queued while it runs, a new turn once it finished", "description": "A run still in flight takes the message at its next turn (202 `queued`); a finished run continues its conversation (its agent session, else a researcher with the prior result as context) and answers 200.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 65536, "description": "The message" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] } }, "required": [ "text" ] } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "The agent’s reply Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string" }, "status": { "type": "string", "description": "running | completed | incomplete | failed | cancelled, or needs_input / needs_approval when the run finished its turn and waits for the user (POST …/continue)" }, "content": { "type": "string", "description": "The agent's reply" }, "continuation": { "type": [ "object", "null" ], "description": "Non-null when the run is paused awaiting the user", "properties": { "status": { "type": "string", "enum": [ "question", "needs_approval" ] }, "agent": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "pending_action": { "type": [ "object", "null" ], "description": "The held action: summary, price, and the permission class / tool when known" } } }, "conversation_recorded": { "type": "boolean", "description": "false when the turn ran but could not be saved to the thread (GET …/conversation lacks it); the reply is still returned" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "202": { "description": "Queued for the live run", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string" }, "queued": { "type": "boolean", "const": true } } } } } }, "400": { "description": "missing_text — body needs a non-empty `text`; invalid_format / invalid_json / invalid_yaml — unreadable body or unknown format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "execution_not_found — no execution with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "followup_failed — no answer; retry; upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "followup-execution" } }, "/v1/executions/{id}/steer": { "post": { "operationId": "post-v1-executions-id-steer", "tags": [ "Executions" ], "summary": "Queue a message for a running execution", "description": "Delivered to the live loop at its next turn. A finished run has no live loop: 409.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 65536, "description": "The message" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ] } }, "required": [ "text" ] } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string" }, "queued": { "type": "boolean", "const": true } } } } } }, "400": { "description": "missing_text — body needs a non-empty `text`; invalid_format / invalid_json / invalid_yaml — unreadable body or unknown format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "execution_not_found — no execution with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "execution_finished — the run is already terminal, nothing to steer or attach to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "steer-execution" } }, "/v1/executions/{id}/cancel": { "post": { "operationId": "post-v1-executions-id-cancel", "tags": [ "Executions" ], "summary": "Cancel a running execution (cooperative)", "description": "The same route as POST /v1/workflows/executions/{id}/cancel: writes the cancel marker the engine and agent loops poll at their next turn or tool boundary and stamps the row cancelled.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "cancelled": { "type": "string" }, "markers": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no such execution for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "not_running — the execution already finished or was cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "cancel-execution" } }, "/v1/executions/{id}/stream": { "get": { "operationId": "get-v1-executions-id-stream", "tags": [ "Executions" ], "summary": "Re-attach to a running execution (SSE)", "description": "Events: `status` (first, then on change), `progress` (one per interior step record of the tasks named in `task`, polled every 250 ms), `done` (terminal, or the run paused for the user, or `reattach: true` after 5 min), `error` (the run vanished mid-stream, e.g. deleted: one event, then the stream closes). A `: ping` comment every 15 s. A re-attach replays the progress records. Interior records exist for runs started with progress watching (async, MCP, Studio, scheduler runs); a plain synchronous REST run writes none and streams status only.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Execution id (the x-execution-id of the run, or its engine id `exec-…`)" }, { "name": "task", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 4 }, "description": "Task ids whose progress records to follow (repeat the parameter, or comma-separate)" } ], "responses": { "200": { "description": "Server-sent events", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_task — more than 4 ids, or an id with other than letters, digits, . : _ -", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "execution_not_found — no execution with that id for this key (a foreign id answers the same); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "execution_finished — the run is already terminal, nothing to steer or attach to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "too_many_streams — a run takes at most 5 live streams at once; close one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — a store failed; no detail is returned, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "stream-execution" } }, "/v1/schedules": { "get": { "operationId": "get-v1-schedules", "tags": [ "Schedules" ], "summary": "List your schedules", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused" ] }, "description": "Only schedules in this state" }, { "name": "job_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "workflow", "heartbeat", "agent", "query" ] }, "description": "Only this type" }, { "name": "workflow_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only the schedules of this saved workflow" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size, 1–100 (default 20)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Rows to skip" } ], "responses": { "200": { "description": "A page of schedules Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "job_type": { "type": "string", "enum": [ "workflow", "heartbeat", "agent", "query" ] }, "schedule": { "type": "string", "description": "Cron expression, or @once for a one-time schedule" }, "timezone": { "type": [ "string", "null" ], "description": "IANA zone the cron is read in; null = UTC" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "workflow_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "description": "The workflow id, or a heartbeat’s JSON spec" }, "parameters": { "type": [ "object", "null" ], "description": "deliver targets, input, … as stored" }, "next_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "last_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "ends_at": { "type": [ "integer", "null" ], "description": "ms epoch after which a due schedule is removed instead of run" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-schedules" }, "post": { "operationId": "post-v1-schedules", "tags": [ "Schedules" ], "summary": "Create a schedule of a saved workflow (cron, or one-time with run_at)", "description": "Runs a saved workflow or bot you own on a cron expression, or once at run_at with schedule \"@once\". parameters.deliver is a list of {channel, chat_id?, to?} (a bare channel string is widened) with channel one of inapp, email, slack, telegram, whatsapp, discord, teams. A heartbeat takes job_type \"heartbeat\" and its spec as target. The owner is always the key's user.", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "schedule" ], "properties": { "name": { "type": "string" }, "schedule": { "type": "string", "description": "Cron expression, or \"@once\" together with run_at" }, "workflow_id": { "type": "string", "description": "The saved workflow or bot to run" }, "job_type": { "type": "string", "enum": [ "workflow", "heartbeat" ], "description": "Default workflow" }, "target": { "description": "A heartbeat’s spec (object or JSON string); for a workflow schedule the workflow id" }, "description": { "type": "string" }, "timezone": { "type": "string", "description": "IANA zone the cron is read in" }, "parameters": { "type": "object", "description": "deliver targets, per-run input, …" }, "run_at": { "type": "string", "description": "ISO-8601 time with a UTC offset, in the future; required when schedule is @once" }, "ends_at": { "description": "ISO-8601 time or ms epoch after which the schedule stops running" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "The schedule Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "job_type": { "type": "string", "enum": [ "workflow", "heartbeat", "agent", "query" ] }, "schedule": { "type": "string", "description": "Cron expression, or @once for a one-time schedule" }, "timezone": { "type": [ "string", "null" ], "description": "IANA zone the cron is read in; null = UTC" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "workflow_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "description": "The workflow id, or a heartbeat’s JSON spec" }, "parameters": { "type": [ "object", "null" ], "description": "deliver targets, input, … as stored" }, "next_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "last_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "ends_at": { "type": [ "integer", "null" ], "description": "ms epoch after which a due schedule is removed instead of run" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text; run_at_required — schedule is @once without run_at; run_at_past — run_at is not in the future; run_at must carry a UTC offset (invalid_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_not_found — no saved workflow with that id for this key; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "create-schedule" } }, "/v1/schedules/{id}": { "get": { "operationId": "get-v1-schedules-id", "tags": [ "Schedules" ], "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id (job_…)" } ], "summary": "Get a schedule with its latest runs", "responses": { "200": { "description": "The schedule and its ten latest runs Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "job_type": { "type": "string", "enum": [ "workflow", "heartbeat", "agent", "query" ] }, "schedule": { "type": "string", "description": "Cron expression, or @once for a one-time schedule" }, "timezone": { "type": [ "string", "null" ], "description": "IANA zone the cron is read in; null = UTC" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "workflow_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "description": "The workflow id, or a heartbeat’s JSON spec" }, "parameters": { "type": [ "object", "null" ], "description": "deliver targets, input, … as stored" }, "next_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "last_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "ends_at": { "type": [ "integer", "null" ], "description": "ms epoch after which a due schedule is removed instead of run" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } }, "recent_runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scheduler’s run id" }, "schedule_id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "cancelled" ] }, "started_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "ended_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "duration_ms": { "type": [ "integer", "null" ] }, "execution_id": { "type": [ "string", "null" ], "description": "The id the executions, results and cancel routes take; null until the engine run exists" }, "triggered_by": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ], "description": "The recorded error, clipped to 300 characters" } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-schedule" }, "patch": { "operationId": "patch-v1-schedules-id", "tags": [ "Schedules" ], "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id (job_…)" } ], "summary": "Change a schedule", "description": "Any of name, description, schedule (a cron — a schedule cannot become @once), timezone, status (active or paused), parameters (replaces the stored object; parameters.deliver is a list of {channel, chat_id?, to?} (a bare channel string is widened) with channel one of inapp, email, slack, telegram, whatsapp, discord, teams.) and ends_at (null clears it).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schedule": { "type": "string" }, "timezone": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "parameters": { "type": "object" }, "ends_at": { "description": "ISO-8601 time or ms epoch; null clears" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "The changed schedule Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "job_type": { "type": "string", "enum": [ "workflow", "heartbeat", "agent", "query" ] }, "schedule": { "type": "string", "description": "Cron expression, or @once for a one-time schedule" }, "timezone": { "type": [ "string", "null" ], "description": "IANA zone the cron is read in; null = UTC" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "workflow_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "description": "The workflow id, or a heartbeat’s JSON spec" }, "parameters": { "type": [ "object", "null" ], "description": "deliver targets, input, … as stored" }, "next_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "last_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "ends_at": { "type": [ "integer", "null" ], "description": "ms epoch after which a due schedule is removed instead of run" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text; invalid_request — the scheduler refused the change (the message says which)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "update-schedule" }, "delete": { "operationId": "delete-v1-schedules-id", "tags": [ "Schedules" ], "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id (job_…)" } ], "summary": "Delete a schedule", "description": "The schedule stops and disappears from lists and GET; its run history stays readable at /runs.", "responses": { "200": { "description": "Deleted Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "delete-schedule" } }, "/v1/schedules/{id}/run": { "post": { "operationId": "post-v1-schedules-id-run", "tags": [ "Schedules" ], "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id (job_…)" } ], "summary": "Run a schedule now", "description": "Also served at /v1/schedules/{id}/execute. Runs the schedule’s workflow once, immediately, as a manual run. `input` replaces the schedule’s own input for this run. execution_id (= cln_workflow_id) is the id the executions, results and cancel routes take; run_id is the scheduler’s record, the id in /runs.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string", "description": "Input for this one run" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "The run was accepted Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "execution_id": { "type": [ "string", "null" ] }, "cln_workflow_id": { "type": [ "string", "null" ] } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "run-schedule" } }, "/v1/schedules/{id}/pause": { "post": { "operationId": "post-v1-schedules-id-pause", "tags": [ "Schedules" ], "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id (job_…)" } ], "summary": "Pause a schedule", "responses": { "200": { "description": "The paused schedule Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "job_type": { "type": "string", "enum": [ "workflow", "heartbeat", "agent", "query" ] }, "schedule": { "type": "string", "description": "Cron expression, or @once for a one-time schedule" }, "timezone": { "type": [ "string", "null" ], "description": "IANA zone the cron is read in; null = UTC" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "workflow_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "description": "The workflow id, or a heartbeat’s JSON spec" }, "parameters": { "type": [ "object", "null" ], "description": "deliver targets, input, … as stored" }, "next_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "last_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "ends_at": { "type": [ "integer", "null" ], "description": "ms epoch after which a due schedule is removed instead of run" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "pause-schedule" } }, "/v1/schedules/{id}/resume": { "post": { "operationId": "post-v1-schedules-id-resume", "tags": [ "Schedules" ], "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id (job_…)" } ], "summary": "Resume a paused schedule", "responses": { "200": { "description": "The active schedule Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "job_type": { "type": "string", "enum": [ "workflow", "heartbeat", "agent", "query" ] }, "schedule": { "type": "string", "description": "Cron expression, or @once for a one-time schedule" }, "timezone": { "type": [ "string", "null" ], "description": "IANA zone the cron is read in; null = UTC" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "workflow_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "description": "The workflow id, or a heartbeat’s JSON spec" }, "parameters": { "type": [ "object", "null" ], "description": "deliver targets, input, … as stored" }, "next_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "last_run_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "ends_at": { "type": [ "integer", "null" ], "description": "ms epoch after which a due schedule is removed instead of run" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "resume-schedule" } }, "/v1/schedules/{id}/wake": { "post": { "operationId": "post-v1-schedules-id-wake", "tags": [ "Schedules" ], "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id (job_…)" } ], "summary": "Wake the schedule’s workflow once", "description": "Fires the schedule’s saved workflow once through a one-time job (the scheduler’s runAgain), without touching the schedule itself. A pending wake is re-timed, never stacked. `in` delays it (seconds, or \"10m\"); the default is the scheduler’s next tick. `note` becomes the run’s input. job_id is the one-time job, next_run_at its ms epoch fire time.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "Why this run exists; becomes its input" }, "in": { "description": "Delay: seconds, or a string like \"90s\", \"10m\", \"2h\"" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "The wake-up Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" }, "next_run_at": { "type": "integer", "description": "ms epoch" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); workflow_not_found — the schedule’s workflow is gone; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written; also a schedule that has no saved workflow (a heartbeat)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "wake-schedule" } }, "/v1/schedules/{id}/runs": { "get": { "operationId": "get-v1-schedules-id-runs", "tags": [ "Schedules" ], "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id (job_…)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "running", "completed", "failed", "cancelled" ] }, "description": "Only runs in this state" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size, 1–100 (default 20)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Rows to skip" } ], "summary": "List a schedule’s runs", "description": "Newest first. Readable after the schedule is deleted.", "responses": { "200": { "description": "A page of runs Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scheduler’s run id" }, "schedule_id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "cancelled" ] }, "started_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "ended_at": { "type": [ "integer", "null" ], "description": "ms epoch" }, "duration_ms": { "type": [ "integer", "null" ] }, "execution_id": { "type": [ "string", "null" ], "description": "The id the executions, results and cancel routes take; null until the engine run exists" }, "triggered_by": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ], "description": "The recorded error, clipped to 300 characters" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-schedule-runs" } }, "/v1/triggers/webhook": { "get": { "operationId": "get-v1-triggers-webhook", "tags": [ "Triggers" ], "summary": "List a schedule's webhook triggers", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The schedule the trigger belongs to" } ], "responses": { "200": { "description": "The webhook triggers; secrets are never listed Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "triggers": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "prompt_template": { "type": [ "string", "null" ] }, "scheme": { "type": [ "string", "null" ] }, "filters": { "type": [ "object", "null" ] }, "created_at": { "type": "integer" }, "last_fired_at": { "type": [ "integer", "null" ] }, "fire_count": { "type": "integer" } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-webhook-triggers" }, "post": { "operationId": "post-v1-triggers-webhook", "tags": [ "Triggers" ], "summary": "Mint a webhook trigger on a schedule", "description": "The response is never cached. A secret in it is shown once and cannot be read again.", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "schedule_id" ], "properties": { "schedule_id": { "type": "string" }, "prompt_template": { "type": "string", "description": "Text for the run’s input; {dotted.path} fills in a field of the JSON payload, e.g. {pull_request.title}" }, "scheme": { "type": "string", "description": "Signature scheme: generic (default), github, gitlab or standard-webhooks" }, "filters": { "type": "object", "description": "{ all?: Rule[], any?: Rule[] } on the payload or headers; up to 20 rules" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "Minted Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "secret": { "type": "string", "description": "HMAC key for the sender; shown once" }, "scheme": { "type": "string" }, "url": { "type": "string", "description": "Where the sender POSTs" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text; invalid_request — the scheduler refused the settings (the message says which)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "create-webhook-trigger" } }, "/v1/triggers/webhook/{token}": { "delete": { "operationId": "delete-v1-triggers-webhook-token", "tags": [ "Triggers" ], "summary": "Revoke a webhook trigger", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trigger token" }, { "name": "schedule_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The schedule the trigger belongs to" } ], "responses": { "200": { "description": "Revoked Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "trigger_not_found — no such trigger on this schedule; schedule_not_found — no schedule with that id for this key; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "delete-webhook-trigger" } }, "/v1/triggers/webhook/{token}/rotate": { "post": { "operationId": "post-v1-triggers-webhook-token-rotate", "tags": [ "Triggers" ], "summary": "Rotate a webhook trigger", "description": "Mints a successor with the same settings, then revokes the old token. A failure in between leaves both live, never neither.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trigger token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "schedule_id" ], "properties": { "schedule_id": { "type": "string" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "The successor (secret shown once), with `rotated` = the revoked token Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "secret": { "type": "string", "description": "HMAC key for the sender; shown once" }, "scheme": { "type": "string" }, "url": { "type": "string", "description": "Where the sender POSTs" }, "rotated": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "trigger_not_found — no such trigger on this schedule; schedule_not_found — no schedule with that id for this key; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "rotate-webhook-trigger" } }, "/v1/triggers/email": { "get": { "operationId": "get-v1-triggers-email", "tags": [ "Triggers" ], "summary": "List a schedule's email triggers", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The schedule the trigger belongs to" } ], "responses": { "200": { "description": "The email triggers; secrets are never listed Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "allowed_from": { "type": [ "string", "null" ] }, "created_at": { "type": "integer" }, "last_fired_at": { "type": [ "integer", "null" ] }, "fire_count": { "type": "integer" } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-email-triggers" }, "post": { "operationId": "post-v1-triggers-email", "tags": [ "Triggers" ], "summary": "Mint an email trigger on a schedule", "description": "The response is never cached. A secret in it is shown once and cannot be read again.", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "schedule_id" ], "properties": { "schedule_id": { "type": "string" }, "allowed_from": { "type": "string", "description": "Comma-separated sender addresses or domains; empty = anyone" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "Minted Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "address_local_part": { "type": "string", "description": "bot+: append @ your Email Routing domain" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text; invalid_request — the scheduler refused the settings (the message says which)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "create-email-trigger" } }, "/v1/triggers/email/{token}": { "delete": { "operationId": "delete-v1-triggers-email-token", "tags": [ "Triggers" ], "summary": "Revoke an email trigger", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trigger token" }, { "name": "schedule_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The schedule the trigger belongs to" } ], "responses": { "200": { "description": "Revoked Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "trigger_not_found — no such trigger on this schedule; schedule_not_found — no schedule with that id for this key; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "delete-email-trigger" } }, "/v1/triggers/email/{token}/rotate": { "post": { "operationId": "post-v1-triggers-email-token-rotate", "tags": [ "Triggers" ], "summary": "Rotate an email trigger", "description": "Mints a successor with the same settings, then revokes the old token. A failure in between leaves both live, never neither.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trigger token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "schedule_id" ], "properties": { "schedule_id": { "type": "string" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "The successor (secret shown once), with `rotated` = the revoked token Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "address_local_part": { "type": "string", "description": "bot+: append @ your Email Routing domain" }, "rotated": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "trigger_not_found — no such trigger on this schedule; schedule_not_found — no schedule with that id for this key; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "rotate-email-trigger" } }, "/v1/triggers/hooks": { "get": { "operationId": "get-v1-triggers-hooks", "tags": [ "Triggers" ], "summary": "List a schedule's outbound hooks", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The schedule the trigger belongs to" } ], "responses": { "200": { "description": "The outbound hooks; secrets are never listed Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "created_at": { "type": "integer" }, "last_delivery_at": { "type": [ "integer", "null" ] }, "last_status": { "type": [ "integer", "null" ] } } } } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "unavailable — outbound hooks are not enabled on this deployment yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-hooks" }, "post": { "operationId": "post-v1-triggers-hooks", "tags": [ "Triggers" ], "summary": "Mint an outbound hook on a schedule", "description": "The response is never cached. A secret in it is shown once and cannot be read again.", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "schedule_id" ], "properties": { "schedule_id": { "type": "string" }, "url": { "type": "string", "description": "https URL that receives the signed run events" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Run events to send: run.started, run.finished, run.failed, run.needs_approval" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } } } }, "text/yaml": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "Minted Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string", "description": "Signing key for X-Ocean-Signature; shown once" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text; invalid_request — the scheduler refused the settings (the message says which)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "schedule_not_found — no schedule with that id for this key (a foreign, missing or deleted id answers alike); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "unavailable — outbound hooks are not enabled on this deployment yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "create-hook" } }, "/v1/triggers/hooks/{id}": { "delete": { "operationId": "delete-v1-triggers-hooks-id", "tags": [ "Triggers" ], "summary": "Revoke an outbound hook", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Hook id" }, { "name": "schedule_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The schedule the trigger belongs to" } ], "responses": { "200": { "description": "Revoked Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "trigger_not_found — no such trigger on this schedule; schedule_not_found — no schedule with that id for this key; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — a field is missing or malformed (the envelope names it); nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "scheduler_error — the scheduler failed or did not answer; no detail is returned, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "unavailable — outbound hooks are not enabled on this deployment yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "delete-hook" } }, "/v1/connections": { "get": { "operationId": "get-v1-connections", "tags": [ "Connections" ], "summary": "List your connections, or one customer’s (status only)", "description": "Provider, how it connected, state and when. No credential, token or hint is ever returned. Without `on_behalf_of` this is your own account’s connections; with it, that customer’s only.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "on_behalf_of", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?!.*\\.\\.)[A-Za-z0-9_.-]{1,128}$" }, "description": "Act on this customer’s connections instead of your own. An empty value is refused." } ], "responses": { "200": { "description": "The connections Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "on_behalf_of": { "type": [ "string", "null" ] }, "method": { "type": "string", "enum": [ "oauth", "api_key", "service_account" ] }, "status": { "type": "string", "enum": [ "active", "expired", "revoked", "error" ] }, "connected_at": { "type": "string", "format": "date-time" } }, "required": [ "provider", "on_behalf_of", "method", "status", "connected_at" ] } } }, "required": [ "connections" ] } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text; invalid_on_behalf_of — on_behalf_of must be 1-128 characters of A-Z a-z 0-9 _ . - (no \"..\")", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "connections_unavailable — connections are not available on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-connections" } }, "/v1/connections/{provider}": { "post": { "operationId": "post-v1-connections-provider", "tags": [ "Connections" ], "summary": "Bring a key for a provider (yours, or your customer’s)", "description": "The key is checked live where the provider has a probe (a rejected key is never stored), then stored encrypted. The next call of a connection-tier agent runs on it. Nothing secret comes back.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector id (`google`, `azure` for Microsoft 365, `github`, `slack`, `stripe`, …). The `connect` pointer in a 424 names it." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "maxLength": 4096 }, "api_secret": { "type": "string", "maxLength": 4096, "description": "Only for providers that issue a second secret." }, "on_behalf_of": { "type": "string", "pattern": "^(?!.*\\.\\.)[A-Za-z0-9_.-]{1,128}$", "description": "Your customer’s id (an opaque string you own): the connection is theirs, stored under your key and reachable only through it. Omit it to connect your own account." }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } }, "required": [ "api_key" ] } } } }, "responses": { "201": { "description": "Connected Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "on_behalf_of": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "connected" ] } }, "required": [ "provider", "on_behalf_of", "status" ] } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "credential_rejected — the provider refused the key; missing_api_key — api_key is required; invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text; invalid_on_behalf_of — on_behalf_of must be 1-128 characters of A-Z a-z 0-9 _ . - (no \"..\")", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_provider — no connector with that provider id; connection_not_found — nothing to disconnect; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "connections_unavailable — connections are not available on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "connect-provider" }, "delete": { "operationId": "delete-v1-connections-provider", "tags": [ "Connections" ], "summary": "Disconnect a provider (yours, or your customer’s)", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector id (`google`, `azure` for Microsoft 365, `github`, `slack`, `stripe`, …). The `connect` pointer in a 424 names it." }, { "name": "on_behalf_of", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(?!.*\\.\\.)[A-Za-z0-9_.-]{1,128}$" }, "description": "Act on this customer’s connections instead of your own. An empty value is refused." } ], "responses": { "204": { "description": "Disconnected" }, "400": { "description": "invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text; invalid_on_behalf_of — on_behalf_of must be 1-128 characters of A-Z a-z 0-9 _ . - (no \"..\")", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_provider — no connector with that provider id; connection_not_found — nothing to disconnect; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "connections_unavailable — connections are not available on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "disconnect-provider" } }, "/v1/connections/{provider}/link": { "post": { "operationId": "post-v1-connections-provider-link", "tags": [ "Connections" ], "summary": "Get a hosted connect link to send to your customer", "description": "A signed URL on studio.plungeai.com that works once and for 15 minutes, with no Studio login: the customer signs in at the provider (or pastes a key) and the connection lands under `on_behalf_of`. With `return_url` they come back to your page with `?connected=`.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector id (`google`, `azure` for Microsoft 365, `github`, `slack`, `stripe`, …). The `connect` pointer in a 424 names it." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "on_behalf_of": { "type": "string", "pattern": "^(?!.*\\.\\.)[A-Za-z0-9_.-]{1,128}$", "description": "Your customer’s id (an opaque string you own): the connection is theirs, stored under your key and reachable only through it. Omit it to connect your own account." }, "return_url": { "type": "string", "format": "uri", "description": "An https URL to send the customer to afterwards." }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (Accept header and the request Content-Type mirror also work). Default json." } }, "required": [] } } } }, "responses": { "201": { "description": "The link Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "url", "expires_at" ] } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_return_url — return_url must be https; invalid_json / invalid_yaml / invalid_body — unreadable body; invalid_format — format must be one of json, yaml, markdown, text; invalid_on_behalf_of — on_behalf_of must be 1-128 characters of A-Z a-z 0-9 _ . - (no \"..\")", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "owner_not_found — the link mint re-reads the owner’s user row; a key whose user no longer exists cannot mint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_provider — no connector with that provider id; connection_not_found — nothing to disconnect; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "connections_unavailable — connections are not available on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "create-connect-link" } }, "/v1/memory/recall": { "get": { "operationId": "get-v1-memory-recall", "tags": [ "Memory" ], "summary": "Recall your long-term memory entries (optionally filtered by text)", "description": "Lists the entries in your MEMORY and USER stores. Memory belongs to the key’s user: nobody else’s entries are ever returned. `q` keeps the entries containing that text (case-insensitive).", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Keep entries containing this text" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Matching entries Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryEntry" } }, "count": { "type": "integer" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_format — format must be one of json, yaml, markdown, text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "recall-memory" } }, "/v1/memory/remember": { "post": { "operationId": "post-v1-memory-remember", "tags": [ "Memory" ], "summary": "Remember a fact", "description": "Adds one entry to your MEMORY store (or your USER profile with `scope: \"user\"`). Saving text that is already stored is a 200 no-op. A refused write (the store is full, or the text matches a threat pattern) is 422 memory_rejected with the current entries to consolidate.", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 65536 }, "scope": { "type": "string", "enum": [ "memory", "user" ], "default": "memory" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } } } }, "responses": { "200": { "description": "The same text was already stored: nothing was added, the existing entry comes back. Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryEntry" } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "201": { "description": "Saved. Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryEntry" } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params (text or scope) · memory_rejected (store full or blocked text; carries current_entries)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "remember" } }, "/v1/memory/forget": { "post": { "operationId": "post-v1-memory-forget", "tags": [ "Memory" ], "summary": "Forget one entry by id, or purge every entry containing some text", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Send exactly one of `id` or `text`.", "properties": { "id": { "type": "string", "description": "An entry id from recall (mem_…)" }, "text": { "type": "string", "description": "Purge every entry containing this text, in both stores" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } } } }, "responses": { "200": { "description": "How many entries were removed Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "integer" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "memory_not_found — no entry with that id in your memory; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "memory_conflict — the id’s text is also contained in another entry; forget by text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — send exactly one of id or text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "forget" } }, "/v1/memory/runs": { "get": { "operationId": "get-v1-memory-runs", "tags": [ "Memory" ], "summary": "Search your past runs", "description": "Keyword search over the runs core-memory stored for your user (full-text index, most relevant first).", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "Matching runs Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "run_id": { "type": "string" }, "ts": { "type": "string" }, "goal": { "type": "string" }, "snippet": { "type": "string" } } } }, "count": { "type": "integer" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — q is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "search-runs" } }, "/v1/memory/runs/{id}": { "get": { "operationId": "get-v1-memory-runs-id", "tags": [ "Memory" ], "summary": "One past run’s stored result", "description": "The `text` and `markdown` wires return the run’s content alone.", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The run Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "content": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "run_not_found — no run with that id in your memory (the same answer for another user’s run); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-run" } }, "/v1/skills": { "get": { "operationId": "get-v1-skills", "tags": [ "Skills" ], "summary": "List your learned skills", "description": "Private skills saved under your key (by `POST /v1/skills/learn`, the `plungeai_learn` tool or an agent’s skill_manage). Platform skills are not listed.", "security": [ { "ozkBearer": [] } ], "responses": { "200": { "description": "Your skills Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } }, "count": { "type": "integer" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "registry_unavailable — the skill registry could not answer; this is not an empty list, retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-skills" } }, "/v1/skills/learn": { "post": { "operationId": "post-v1-skills-learn", "tags": [ "Skills" ], "summary": "Save a skill", "description": "Saves a skill you wrote as a private card others cannot read, inject or delete — the card `skill_manage create` writes. Saving an existing name of your own replaces it; a name held by a platform skill or another user is 409. Inject it into a mission with `skills: []`. To have an agent distil a skill from a URL or text instead, use the `plungeai_learn` MCP tool.", "security": [ { "ozkBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "body" ], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$", "description": "Kebab-case id, 2 to 64 characters" }, "body": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "The skill, in markdown" }, "description": { "type": "string", "maxLength": 60, "description": "One line; defaults to the body’s first line" }, "format": { "type": "string", "enum": [ "json", "yaml", "markdown", "text" ], "description": "Response format override (precedence: this field → Accept header → mirror of the request Content-Type). Default json. yaml = the envelope with Markdown as block scalars; markdown = the same result the MCP plane renders; text = the bare result content. An unknown value → 400 invalid_format." } } } } } }, "responses": { "201": { "description": "Saved. Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "$ref": "#/components/schemas/Skill" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "invalid_json — body is not valid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "skill_name_taken — the name belongs to a platform skill or another user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — name, body or description is missing or out of bounds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "upstream_error — the skill store refused the write; nothing was saved, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "learn-skill" } }, "/v1/skills/{id}": { "delete": { "operationId": "delete-v1-skills-id", "tags": [ "Skills" ], "summary": "Delete one of your skills", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "skill_not_found — no skill of yours with that id (the same answer for a platform or another user’s skill); not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "registry_unavailable — the skill registry could not answer, so nothing was deleted (this is not a 404); retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "delete-skill" } }, "/v1/templates": { "get": { "operationId": "get-v1-templates", "tags": [ "Templates" ], "summary": "Browse the workflow, agent and bot templates", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "workflow", "agent", "bot" ] } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Active templates, featured first Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "count": { "type": "integer" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_params — kind must be one of workflow, agent, bot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "list-templates" } }, "/v1/templates/{id}": { "get": { "operationId": "get-v1-templates-id", "tags": [ "Templates" ], "summary": "One template and its YAML", "security": [ { "ozkBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The template Response format negotiates via the `format` field, an Accept header (application/json, text/yaml, text/markdown, text/plain), or the request Content-Type mirror; default JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/Template" }, "yaml": { "type": "string" } } } }, "text/yaml": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked ozk_ key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "template_not_found — no active template with that id; not_found — no route for this method on this path: every other method answers it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-docs-slug": "get-template" } }, "/v1/templates/{id}/use": { "post": { "operationId": "post-v1-templates-id-use", "tags": [ "Templates" ], "summary": "Copy a template into your account as a new workflow", "description": "Creates a saved workflow from the template’s YAML, carrying its kind. A bot template keeps its name; the others are named \"