{ "openapi": "3.1.0", "info": { "title": "Orch8.io API", "description": "Durable task sequencing engine — REST API.\n\nAll versioned endpoints are available under the `/api/v1` prefix (canonical) and also at the bare path for backward compatibility. Bare-path responses carry Deprecation, Sunset, and successor-version + Link headers. Health and metrics endpoints remain at the root + (`/health/*`, `/metrics`).", "license": { "name": "BUSL-1.1" }, "version": "1.0.0" }, "servers": [ { "url": "/api/v1", "description": "Versioned API (canonical)" }, { "url": "/", "description": "Unversioned (deprecated, backward-compat)" } ], "paths": { "/alerts/rules": { "get": { "tags": [ "alerts" ], "operationId": "list_rules", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers only)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Alert rules", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRule" } } } } } } }, "post": { "tags": [ "alerts" ], "operationId": "create_rule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleRequest" } } }, "required": true }, "responses": { "201": { "description": "Rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" } } } }, "400": { "description": "Invalid rule (e.g. literal secret instead of credentials:// reference)" } } } }, "/alerts/rules/{id}": { "get": { "tags": [ "alerts" ], "operationId": "get_rule", "parameters": [ { "name": "id", "in": "path", "description": "Rule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rule with evaluator state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleView" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "alerts" ], "operationId": "update_rule", "parameters": [ { "name": "id", "in": "path", "description": "Rule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRuleRequest" } } }, "required": true }, "responses": { "200": { "description": "Rule replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" } } } }, "400": { "description": "Invalid rule" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "alerts" ], "operationId": "delete_rule", "parameters": [ { "name": "id", "in": "path", "description": "Rule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/approvals/act/{token}": { "get": { "tags": [ "approvals" ], "operationId": "confirm_page", "parameters": [ { "name": "token", "in": "path", "description": "Approval magic-link token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmation page (no state change)", "content": { "text/html": {} } }, "410": { "description": "Unknown, used, or expired link", "content": { "text/html": {} } } } }, "post": { "tags": [ "approvals" ], "operationId": "act", "parameters": [ { "name": "token", "in": "path", "description": "Approval magic-link token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional `comment` (form field or JSON `{\"comment\"}`)", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Decision recorded" }, "409": { "description": "Workflow already finished" }, "410": { "description": "Unknown, used, or expired link" } } } }, "/approvals/slack/interactions": { "post": { "tags": [ "approvals" ], "operationId": "slack_interaction", "requestBody": { "description": "Slack interactivity payload", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Interaction processed (Slack requires 200)" }, "401": { "description": "Bad Slack signature, stale timestamp, or unknown token" } } } }, "/artifacts/{key}": { "get": { "tags": [ "instances" ], "operationId": "get_artifact_bytes", "parameters": [ { "name": "key", "in": "path", "description": "Artifact object key (`/`); the route is the wildcard `/artifacts/{*key}`, so the key keeps its slashes", "required": true, "schema": { "type": "string" } }, { "name": "content_type", "in": "query", "description": "Override response Content-Type", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw artifact bytes" }, "404": { "description": "Artifact not found" } } } }, "/budgets": { "get": { "tags": [ "budgets" ], "operationId": "list_budgets", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Budgets with current-period spend and state", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetStatus" } } } } } } }, "post": { "tags": [ "budgets" ], "operationId": "create_budget", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBudget" } } } }, "400": { "description": "Invalid budget" }, "403": { "description": "Requires the root/admin API key" } } } }, "/budgets/alerts": { "get": { "tags": [ "budgets" ], "operationId": "list_alerts", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers)", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max alerts (default 100, max 1000)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "`budget.threshold_crossed` records, newest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetAlert" } } } } } } } }, "/budgets/{id}": { "put": { "tags": [ "budgets" ], "operationId": "update_budget", "parameters": [ { "name": "id", "in": "path", "description": "Budget id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBudget" } } } }, "403": { "description": "Requires the root/admin API key" }, "404": {} } }, "delete": { "tags": [ "budgets" ], "operationId": "delete_budget", "parameters": [ { "name": "id", "in": "path", "description": "Budget id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers)", "required": false, "schema": { "type": "string" } } ], "responses": { "204": {}, "403": {}, "404": {} } } }, "/changes": { "get": { "tags": [ "changes" ], "operationId": "list_changes", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Required without X-Tenant-Id", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Exclusive opaque cursor from next_cursor", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, capped at 500", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Ascending tenant state changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePage" } } } }, "400": { "description": "Missing tenant or malformed cursor" } } } }, "/changes/stream": { "get": { "tags": [ "changes" ], "operationId": "stream_changes", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Required without X-Tenant-Id", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Overrides Last-Event-ID when supplied", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum changes fetched per poll", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Resumable tenant change stream (SSE)" }, "400": { "description": "Missing tenant or malformed cursor" }, "429": { "description": "Concurrent stream limit reached" } } } }, "/circuit-breakers": { "get": { "tags": [ "crate::circuit_breakers" ], "operationId": "list_all_breakers", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CircuitBreakerState" } } } } } } } }, "/cluster/nodes": { "get": { "tags": [ "crate::cluster" ], "operationId": "list_nodes", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterNode" } } } } } } } }, "/cluster/nodes/{id}/drain": { "post": { "tags": [ "crate::cluster" ], "operationId": "drain_node", "parameters": [ { "name": "id", "in": "path", "description": "Node ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Drain signal sent" } } } }, "/continuity/attention": { "post": { "tags": [ "continuity" ], "operationId": "create_attention_task", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/attention/{id}/assign": { "post": { "tags": [ "continuity" ], "operationId": "assign_attention_task", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/attention/{id}/decide": { "post": { "tags": [ "continuity" ], "operationId": "decide_attention_task", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/capsules/import": { "post": { "tags": [ "continuity" ], "operationId": "import_capsule", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/commercial/validate": { "post": { "tags": [ "continuity-product" ], "operationId": "validate_commercial_plan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercialContinuityPlan" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" } } } }, "400": { "description": "Deployment violates a mandatory commercial invariant" } } } }, "/continuity/compensations/{id}": { "get": { "tags": [ "continuity" ], "operationId": "get_compensation_run", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/compensations/{id}/claim": { "post": { "tags": [ "continuity" ], "operationId": "claim_compensation_step", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/compensations/{id}/steps/{effect_id}/complete": { "post": { "tags": [ "continuity" ], "operationId": "complete_compensation_step", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/compensations/{id}/steps/{effect_id}/fail": { "post": { "tags": [ "continuity" ], "operationId": "fail_compensation_step", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/compensations/{id}/steps/{effect_id}/verify": { "post": { "tags": [ "continuity" ], "operationId": "verify_compensation_step", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/conformance/badge": { "post": { "tags": [ "continuity-product" ], "operationId": "render_badge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConformanceCertificate" } } }, "required": true }, "responses": { "200": { "description": "Server-verified SVG badge", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "400": { "description": "Certificate is invalid, expired, or tampered" } } } }, "/continuity/conformance/certificates": { "post": { "tags": [ "continuity-product" ], "operationId": "certify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConformanceCertificate" } } } }, "400": { "description": "Results or certificate window do not qualify" }, "503": { "description": "Signing is not configured" } } } }, "/continuity/delegations/claim": { "post": { "tags": [ "continuity" ], "operationId": "claim_delegation", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/delegations/{id}": { "get": { "tags": [ "continuity" ], "operationId": "get_delegation", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/disclosure/minimize": { "post": { "tags": [ "continuity" ], "operationId": "minimize_disclosure", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/effects/{id}/resolve": { "post": { "tags": [ "continuity" ], "operationId": "resolve_effect", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/evaluations/gate": { "post": { "tags": [ "continuity" ], "operationId": "evaluate_gate", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/evaluations/stored-gate": { "post": { "tags": [ "continuity" ], "operationId": "evaluate_stored_gate", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions": { "post": { "tags": [ "continuity" ], "operationId": "create_execution", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}": { "get": { "tags": [ "continuity" ], "operationId": "get_execution", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/budget-reservations": { "get": { "tags": [ "continuity" ], "operationId": "list_execution_budget_reservations", "responses": { "default": { "description": "Continuity API response" } } }, "post": { "tags": [ "continuity" ], "operationId": "reserve_execution_budget", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/budget-reservations/{reservation_id}/reconcile": { "post": { "tags": [ "continuity" ], "operationId": "reconcile_execution_budget", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/budget-reservations/{reservation_id}/release": { "post": { "tags": [ "continuity" ], "operationId": "release_execution_budget", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/checkpoints": { "get": { "tags": [ "continuity" ], "operationId": "list_continuity_checkpoints", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/checkpoints/{checkpoint_id}": { "get": { "tags": [ "continuity" ], "operationId": "get_continuity_checkpoint", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/compensations": { "post": { "tags": [ "continuity" ], "operationId": "create_compensation_run", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/compensations/preview": { "post": { "tags": [ "continuity" ], "operationId": "preview_compensation", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/effects": { "get": { "tags": [ "continuity" ], "operationId": "list_effects", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/evaluations": { "get": { "tags": [ "continuity" ], "operationId": "list_evaluations", "responses": { "default": { "description": "Continuity API response" } } }, "post": { "tags": [ "continuity" ], "operationId": "append_evaluation", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/handoff-preview": { "post": { "tags": [ "continuity" ], "operationId": "handoff_preview", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/invariants/evaluate": { "post": { "tags": [ "continuity" ], "operationId": "evaluate_invariants", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/invariants/results": { "get": { "tags": [ "continuity" ], "operationId": "list_invariant_results", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/locations": { "get": { "tags": [ "continuity" ], "operationId": "list_locations", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/placement": { "post": { "tags": [ "continuity" ], "operationId": "choose_placement", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/provenance": { "get": { "tags": [ "continuity" ], "operationId": "list_provenance", "responses": { "default": { "description": "Continuity API response" } } }, "post": { "tags": [ "continuity" ], "operationId": "record_provenance_boundary", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/provenance/verify": { "get": { "tags": [ "continuity" ], "operationId": "verify_provenance", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/test-fixture": { "post": { "tags": [ "continuity" ], "operationId": "extract_test_fixture", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/executions/{id}/what-if": { "get": { "tags": [ "continuity" ], "operationId": "list_what_if_runs", "responses": { "default": { "description": "Continuity API response" } } }, "post": { "tags": [ "continuity" ], "operationId": "run_what_if", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/fault-lab/run": { "post": { "tags": [ "continuity" ], "operationId": "run_fault_lab", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/federation/sign": { "post": { "tags": [ "continuity" ], "operationId": "sign_federation", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/federation/verify": { "post": { "tags": [ "continuity" ], "operationId": "verify_federation", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/gateways/validate": { "post": { "tags": [ "continuity-product" ], "operationId": "validate_gateway", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayManifest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompiledPlacementPolicy" } } } }, "400": { "description": "Gateway manifest is unsafe or invalid" } } } }, "/continuity/grants": { "post": { "tags": [ "continuity" ], "operationId": "issue_continuation_grant", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/grants/consume": { "post": { "tags": [ "continuity" ], "operationId": "consume_continuation_grant", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs": { "post": { "tags": [ "continuity" ], "operationId": "create_handoff", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs/{id}": { "get": { "tags": [ "continuity" ], "operationId": "get_handoff", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs/{id}/accept": { "post": { "tags": [ "continuity" ], "operationId": "accept_handoff", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs/{id}/accept-external": { "post": { "tags": [ "continuity" ], "operationId": "accept_external_handoff", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs/{id}/attach-device-capsule": { "post": { "tags": [ "continuity" ], "operationId": "attach_device_capsule", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs/{id}/export": { "post": { "tags": [ "continuity" ], "operationId": "export_handoff", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs/{id}/reject": { "post": { "tags": [ "continuity" ], "operationId": "reject_handoff", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs/{id}/resume": { "post": { "tags": [ "continuity" ], "operationId": "resume_handoff", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs/{id}/resume-external": { "post": { "tags": [ "continuity" ], "operationId": "resume_external_handoff", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/handoffs/{id}/revoke": { "post": { "tags": [ "continuity" ], "operationId": "revoke_handoff", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/invariants": { "get": { "tags": [ "continuity" ], "operationId": "list_invariants", "responses": { "default": { "description": "Continuity API response" } } }, "post": { "tags": [ "continuity" ], "operationId": "create_invariant", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/migrations/plan": { "post": { "tags": [ "continuity" ], "operationId": "plan_live_migration", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/migrations/{id}": { "get": { "tags": [ "continuity" ], "operationId": "get_live_migration", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/migrations/{id}/apply": { "post": { "tags": [ "continuity" ], "operationId": "apply_live_migration", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/migrations/{id}/rollback": { "post": { "tags": [ "continuity" ], "operationId": "rollback_live_migration", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/offers/validate": { "post": { "tags": [ "continuity-product" ], "operationId": "validate_offer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortableWorkOffer" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" } } } }, "400": { "description": "Offer violates the protocol contract" } } } }, "/continuity/optimizations/recommend": { "post": { "tags": [ "continuity" ], "operationId": "recommend_optimizations", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/optimizations/{id}/accept": { "post": { "tags": [ "continuity" ], "operationId": "accept_optimization", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/policies/compile": { "post": { "tags": [ "continuity-product" ], "operationId": "compile_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompilePolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompiledPlacementPolicy" } } } }, "400": { "description": "Policy is invalid or contains unknown keys" } } } }, "/continuity/profiles": { "get": { "tags": [ "continuity-product" ], "operationId": "list_profiles", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileContract" } } } } } } } }, "/continuity/profiles/{profile}/offers": { "post": { "tags": [ "continuity-product" ], "operationId": "create_profile_offer", "parameters": [ { "name": "profile", "in": "path", "description": "Snake-case trust-boundary profile name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileOfferRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortableWorkOffer" } } } }, "400": { "description": "Unknown profile or invalid offer" } } } }, "/continuity/protocol": { "get": { "tags": [ "continuity-product" ], "operationId": "protocol_description", "responses": { "200": { "description": "Versioned handoff protocol and invariants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolDescription" } } } } } } }, "/continuity/providers/choose": { "post": { "tags": [ "continuity" ], "operationId": "choose_provider", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/receipts/verify": { "post": { "tags": [ "continuity-product" ], "operationId": "verify_receipt", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionReceipt" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" } } } }, "400": { "description": "Receipt is incomplete or its digest does not match" } } } }, "/continuity/residency/evaluate": { "post": { "tags": [ "continuity" ], "operationId": "evaluate_residency", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/scenarios/generate": { "post": { "tags": [ "continuity" ], "operationId": "generate_scenarios", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/scenarios/reproduce": { "post": { "tags": [ "continuity" ], "operationId": "reproduce_incident", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/streams": { "post": { "tags": [ "continuity" ], "operationId": "create_stream", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/streams/{id}/frames": { "get": { "tags": [ "continuity" ], "operationId": "list_stream_frames", "responses": { "default": { "description": "Continuity API response" } } }, "post": { "tags": [ "continuity" ], "operationId": "append_stream_frame", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/streams/{id}/retract": { "post": { "tags": [ "continuity" ], "operationId": "retract_stream_frames", "responses": { "default": { "description": "Continuity API response" } } } }, "/continuity/streams/{id}/windows": { "get": { "tags": [ "continuity" ], "operationId": "list_stream_windows", "responses": { "default": { "description": "Continuity API response" } } } }, "/cron": { "get": { "tags": [ "cron" ], "operationId": "list_cron", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of cron schedules", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CronSchedule" } } } } } } }, "post": { "tags": [ "cron" ], "operationId": "create_cron", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCronRequest" } } }, "required": true }, "responses": { "201": { "description": "Cron schedule created", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid cron expression" } } } }, "/cron/{id}": { "get": { "tags": [ "cron" ], "operationId": "get_cron", "parameters": [ { "name": "id", "in": "path", "description": "Cron schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cron schedule found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CronSchedule" } } } }, "404": { "description": "Cron schedule not found" } } }, "put": { "tags": [ "cron" ], "operationId": "update_cron", "parameters": [ { "name": "id", "in": "path", "description": "Cron schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCronRequest" } } }, "required": true }, "responses": { "200": { "description": "Cron schedule updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CronSchedule" } } } }, "400": { "description": "Invalid cron expression" }, "404": { "description": "Cron schedule not found" } } }, "delete": { "tags": [ "cron" ], "operationId": "delete_cron", "parameters": [ { "name": "id", "in": "path", "description": "Cron schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Cron schedule deleted" } } } }, "/cron/{id}/next-fires": { "get": { "tags": [ "cron" ], "operationId": "next_fires", "parameters": [ { "name": "id", "in": "path", "description": "Cron schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "n", "in": "query", "description": "How many upcoming fires to preview (default 5, max 50)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Upcoming fire instants (UTC, DST-correct)", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Cron schedule not found" } } } }, "/debug/template": { "post": { "tags": [ "debug" ], "operationId": "debug_template_endpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebugTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "Resolved template value with provenance trace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebugTemplateResponse" } } } } } } }, "/embed/approvals": { "get": { "tags": [ "embed" ], "operationId": "embed_list_approvals", "responses": { "200": { "description": "Pending approvals of the sub-tenant's runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedApprovalList" } } } }, "403": { "description": "Token lacks approvals:resolve" } }, "security": [ { "embed_token": [] } ] } }, "/embed/approvals/{id}": { "post": { "tags": [ "embed" ], "operationId": "embed_resolve_approval", "parameters": [ { "name": "id", "in": "path", "description": "Approval id from GET /embed/approvals", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveApprovalRequest" } } }, "required": true }, "responses": { "202": { "description": "Decision recorded", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Choice is not offered by the approval" }, "404": { "description": "Unknown or foreign approval" }, "409": { "description": "Already resolved, or the run already finished" } }, "security": [ { "embed_token": [] } ] } }, "/embed/runs": { "get": { "tags": [ "embed" ], "operationId": "embed_list_runs", "parameters": [ { "name": "limit", "in": "query", "description": "Page size (default 20, max 100).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous page.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "The sub-tenant's runs, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedRunList" } } } }, "401": { "description": "Missing/invalid embed token" }, "403": { "description": "Token lacks runs:read" }, "404": { "description": "Embedding is disabled" } }, "security": [ { "embed_token": [] } ] }, "post": { "tags": [ "embed" ], "operationId": "embed_start_run", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartRunRequest" } } }, "required": true }, "responses": { "201": { "description": "Run started for the token's sub-tenant", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Token lacks runs:start or the sequence" }, "404": { "description": "Unknown/invisible sequence, or embedding disabled" }, "429": { "description": "Tenant pool or sub-tenant cap reached (`sub_tenant_quota_exceeded`)" } }, "security": [ { "embed_token": [] } ] } }, "/embed/runs/{id}": { "get": { "tags": [ "embed" ], "operationId": "embed_get_run", "parameters": [ { "name": "id", "in": "path", "description": "Run (instance) id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run timeline; outputs only for opted-in steps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedRunDetail" } } } }, "404": { "description": "Unknown, foreign, or embedding disabled" } }, "security": [ { "embed_token": [] } ] } }, "/embed/sequences": { "get": { "tags": [ "embed" ], "operationId": "embed_list_sequences", "responses": { "200": { "description": "Latest version of every sequence visible to the sub-tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedSequenceList" } } } }, "403": { "description": "Token lacks sequences:read / builder:edit / runs:start" } }, "security": [ { "embed_token": [] } ] } }, "/embed/sequences/{name}": { "get": { "tags": [ "embed" ], "operationId": "embed_get_sequence", "parameters": [ { "name": "name", "in": "path", "description": "Sequence name", "required": true, "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "description": "Namespace (default `default`).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Summary + `definition`. Owned sequences and gallery templates carry the full definition; other tenant-level sequences an allow-list projection (block types, ids, handler names, nesting; `redacted: true`)", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Unknown or not visible" } }, "security": [ { "embed_token": [] } ] }, "put": { "tags": [ "embed" ], "operationId": "embed_put_sequence", "parameters": [ { "name": "name", "in": "path", "description": "Sequence name", "required": true, "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "description": "Namespace (default `default`).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "description": "Sequence document (blocks, input_schema, embed, …); identity fields are server-assigned", "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "201": { "description": "New version created, owned by the token's sub-tenant", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Token lacks builder:edit or the sequence" }, "409": { "description": "The name belongs to the tenant or another sub-tenant" }, "413": { "description": "Body exceeds 1 MiB" }, "422": { "description": "Rejected by the embed sandbox: a handler outside the allowlist (`[embed] sandbox_handlers`), a `credentials://` reference, or a `sub_sequence` target the sub-tenant does not own" }, "429": { "description": "Per-sequence version cap or per-sub-tenant sequence cap reached (`sub_tenant_quota_exceeded`)" } }, "security": [ { "embed_token": [] } ] } }, "/embed/theme": { "get": { "tags": [ "embed" ], "operationId": "embed_get_theme", "responses": { "200": { "description": "Tenant embed theme (embed token or tenant API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThemeResponse" } } } }, "401": { "description": "Missing/invalid embed token" }, "404": { "description": "Embedding is disabled" } }, "security": [ { "embed_token": [] } ] }, "put": { "tags": [ "embed" ], "operationId": "embed_put_theme", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedTheme" } } }, "required": true }, "responses": { "200": { "description": "Stored; `hide_badge` reports the effective (license-gated) value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThemeResponse" } } } }, "400": { "description": "Invalid theme" }, "404": { "description": "Embedding is disabled" } } } }, "/embed/tokens": { "post": { "tags": [ "embed" ], "operationId": "embed_issue_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueTokenRequest" } } }, "required": true }, "responses": { "201": { "description": "Scoped embed token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueTokenResponse" } } } }, "400": { "description": "Invalid sub-tenant, scopes, sequences or TTL" }, "404": { "description": "Embedding is disabled (no token secret)" } } } }, "/embed/tokens/{jti}/revoke": { "post": { "tags": [ "embed" ], "operationId": "embed_revoke_token", "parameters": [ { "name": "jti", "in": "path", "description": "Token id (`token_id` from the mint response)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Token revoked; it is refused within a few seconds" }, "403": { "description": "Operator capability required" }, "404": { "description": "Embedding is disabled" } } } }, "/events": { "get": { "tags": [ "events" ], "operationId": "list_events", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "pending | consumed | expired", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows (default 100, max 1000)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Rows to skip", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "paged", "in": "query", "description": "Return items, offset and has_more metadata instead of an array", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Events, newest first (payloads redacted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListResponse" } } } } } }, "post": { "tags": [ "events" ], "operationId": "ingest_event", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestEventRequest" } } }, "required": true }, "responses": { "200": { "description": "Duplicate producer id — already ingested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestOutcome" } } } }, "201": { "description": "Event ingested (and possibly matched)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestOutcome" } } } }, "400": { "description": "Missing fields" } } } }, "/events/batch": { "post": { "tags": [ "events" ], "operationId": "ingest_event_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchIngestRequest" } } }, "required": true }, "responses": { "200": { "description": "Outbox batch accepted; individual duplicates are reported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchIngestResponse" } } } }, "400": { "description": "Empty, oversized, or invalid batch" } } } }, "/events/{id}": { "get": { "tags": [ "events" ], "operationId": "get_event", "parameters": [ { "name": "id", "in": "path", "description": "Event id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event (payload redacted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventEnvelope" } } } }, "404": { "description": "Not found" } } } }, "/federation/calls/{call_id}": { "get": { "tags": [ "federation" ], "operationId": "get_call", "parameters": [ { "name": "call_id", "in": "path", "description": "Outbound call id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (ignored when the caller is bound to a tenant by its key/header).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationCall" } } } }, "404": {} } } }, "/federation/identity": { "get": { "tags": [ "federation" ], "operationId": "get_identity", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationIdentity" } } } }, "503": { "description": "No engine encryption key configured" } } } }, "/federation/inbound": { "post": { "tags": [ "federation" ], "operationId": "inbound", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedFederationMessage" } } }, "required": true }, "responses": { "200": { "description": "Signed response envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedFederationMessage" } } } }, "401": { "description": "Envelope outside its validity window (clock skew)" }, "403": { "description": "Unknown/revoked/expired peer, bad signature, or policy denial" }, "404": { "description": "Allowed sequence is not deployed" }, "503": { "description": "Federation disabled (no engine encryption key)" } }, "security": [ {} ] } }, "/federation/peers": { "get": { "tags": [ "federation" ], "operationId": "list_peers", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant (ignored when the caller is bound to a tenant by its key/header).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FederationPeerRecord" } } } } } } }, "post": { "tags": [ "federation" ], "operationId": "create_peer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeerRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationPeerRecord" } } } }, "400": { "description": "Invalid peer (identity/key mismatch, non-HTTPS endpoint, wildcard disclosure for an organization peer)" }, "403": { "description": "Requires the root/admin API key" }, "409": { "description": "Peer already registered" } } } }, "/federation/peers/{peer_id}": { "get": { "tags": [ "federation" ], "operationId": "get_peer", "parameters": [ { "name": "peer_id", "in": "path", "description": "Peer federation id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (ignored when the caller is bound to a tenant by its key/header).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationPeerRecord" } } } }, "404": {} } }, "put": { "tags": [ "federation" ], "operationId": "update_peer", "parameters": [ { "name": "peer_id", "in": "path", "description": "Peer federation id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationPeerRecord" } } } }, "403": { "description": "Requires the root/admin API key" }, "404": {} } }, "delete": { "tags": [ "federation" ], "operationId": "delete_peer", "parameters": [ { "name": "peer_id", "in": "path", "description": "Peer federation id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (ignored when the caller is bound to a tenant by its key/header).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "204": {}, "403": { "description": "Requires the root/admin API key" }, "404": {} } } }, "/handlers": { "get": { "tags": [ "workers" ], "operationId": "list_handlers", "responses": { "200": { "description": "Handler catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandlerCatalog" } } } } } } }, "/health/live": { "get": { "tags": [ "health" ], "summary": "Liveness probe: returns 200 while the process is running, unless an engine\nruns here and its tick loop has not completed an iteration within\n`engine.liveness_stale_secs` — then 503, so the orchestrator restarts a\nwedged scheduler instead of keeping it forever (I-H11).", "operationId": "liveness", "responses": { "200": { "description": "Process is alive" }, "503": { "description": "Engine tick loop is wedged" } } } }, "/health/ready": { "get": { "tags": [ "health" ], "summary": "Readiness probe: returns 200 only if the database is reachable AND the\nengine tick loop is still running and ticking. A dead or wedged scheduler\nwith a live DB must not report ready — otherwise the LB keeps routing to a\nserver that accepts work but never executes it.", "operationId": "readiness", "responses": { "200": { "description": "Database reachable and engine running" }, "503": { "description": "Database unreachable or engine stopped or stalled" } } } }, "/info": { "get": { "tags": [ "health" ], "summary": "Deployment info for UI chrome: engine version plus the optional\noperator-set environment label/color (`ORCH8_ENV_LABEL`,\n`ORCH8_ENV_COLOR`). Read straight from the environment — this is\ncosmetic metadata, not engine configuration, so it does not flow\nthrough `EngineConfig`.", "operationId": "info", "responses": { "200": { "description": "Engine version and environment label" } } } }, "/instances": { "get": { "tags": [ "instances" ], "operationId": "list_instances", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "description": "Filter by namespace", "required": false, "schema": { "type": "string" } }, { "name": "sequence_id", "in": "query", "description": "Filter by sequence", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "state", "in": "query", "description": "Comma-separated states", "required": false, "schema": { "type": "string" } }, { "name": "sub_tenant", "in": "query", "description": "Filter by sub-tenant (X-Orch8-Sub-Tenant overrides)", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Pagination limit (max 1000)", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "List of instances", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaskInstance" } } } } } } }, "post": { "tags": [ "instances" ], "operationId": "create_instance", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInstanceRequest" } } }, "required": true }, "responses": { "200": { "description": "Deduplicated (idempotency key match)", "content": { "application/json": { "schema": {} } } }, "201": { "description": "Instance created", "content": { "application/json": { "schema": {} } } } } } }, "/instances/batch": { "post": { "tags": [ "instances" ], "operationId": "create_instances_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Batch created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } }, "400": { "description": "Empty batch" } } } }, "/instances/batch-action": { "post": { "tags": [ "instances" ], "summary": "Apply one control action to every instance matching a filter. Capped,\naudited, and dry-run-able. Tenant-scoped — a tenant can only act on its own\ninstances.", "operationId": "batch_action", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchActionRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch action result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchActionResponse" } } } }, "400": { "description": "Missing tenant or invalid action params" } } } }, "/instances/bulk/reschedule": { "patch": { "tags": [ "instances" ], "operationId": "bulk_reschedule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRescheduleRequest" } } }, "required": true }, "responses": { "200": { "description": "Bulk reschedule result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } } } } }, "/instances/bulk/state": { "patch": { "tags": [ "instances" ], "operationId": "bulk_update_state", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateStateRequest" } } }, "required": true }, "responses": { "200": { "description": "Bulk state update result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } } } } }, "/instances/dlq": { "get": { "tags": [ "instances" ], "summary": "DLQ: list failed instances.", "operationId": "list_dlq", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "description": "Filter by namespace", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Pagination limit", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Failed instances (DLQ)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaskInstance" } } } } } } } }, "/instances/dlq/groups": { "get": { "tags": [ "instances" ], "operationId": "list_groups", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } }, { "name": "sequence_id", "in": "query", "description": "Filter by sequence", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Failed instances grouped by root-cause fingerprint,\n ordered by affected count then recency", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DlqGroup" } } } } } } } }, "/instances/dlq/groups/{fingerprint}/retry": { "post": { "tags": [ "instances" ], "operationId": "retry_group", "parameters": [ { "name": "fingerprint", "in": "path", "description": "Group fingerprint hash", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DlqGroupRetryRequest" } } }, "required": true }, "responses": { "200": { "description": "Retry outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DlqGroupRetryResponse" } } } }, "404": { "description": "No failed instances match this fingerprint" }, "409": { "description": "Bulk retry not unlocked: no verified sample and no force" } } } }, "/instances/{id}": { "get": { "tags": [ "instances" ], "operationId": "get_instance", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Instance found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskInstance" } } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/artifacts": { "get": { "tags": [ "instances" ], "operationId": "list_instance_artifacts", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Artifact metadata for the instance", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/audit": { "get": { "tags": [ "crate::instances" ], "operationId": "list_audit_log", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } } } } } } } }, "/instances/{id}/blocks/{block_id}/resolved-input": { "get": { "tags": [ "instances" ], "operationId": "inspect_instance_block", "parameters": [ { "name": "id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "block_id", "in": "path", "description": "Step block id", "required": true, "schema": { "type": "string" } }, { "name": "at_block", "in": "query", "description": "Historical boundary block", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolution trace for the block against the instance snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionTrace" } } } }, "404": { "description": "Instance, sequence, or block not found" } } } }, "/instances/{id}/checkpoints": { "get": { "tags": [ "instances" ], "operationId": "list_checkpoints", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of checkpoints", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Checkpoint" } } } } } } }, "post": { "tags": [ "instances" ], "operationId": "save_checkpoint", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveCheckpointRequest" } } }, "required": true }, "responses": { "201": { "description": "Checkpoint saved", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/checkpoints/latest": { "get": { "tags": [ "instances" ], "operationId": "get_latest_checkpoint", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Latest checkpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkpoint" } } } }, "404": { "description": "No checkpoint found" } } } }, "/instances/{id}/checkpoints/prune": { "post": { "tags": [ "instances" ], "operationId": "prune_checkpoints", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PruneCheckpointsRequest" } } }, "required": true }, "responses": { "200": { "description": "Pruned checkpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountResponse" } } } } } } }, "/instances/{id}/children": { "get": { "tags": [ "instances" ], "operationId": "get_instance_children", "parameters": [ { "name": "id", "in": "path", "description": "Parent instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Child instances spawned by this instance", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaskInstance" } } } } }, "404": { "description": "Parent instance not found" } } } }, "/instances/{id}/compare/{other}": { "get": { "tags": [ "instances" ], "operationId": "compare_runs", "parameters": [ { "name": "id", "in": "path", "description": "Left instance", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "other", "in": "path", "description": "Right instance", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Path and output comparison (no payloads)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunComparison" } } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/context": { "patch": { "tags": [ "instances" ], "operationId": "update_context", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContextRequest" } } }, "required": true }, "responses": { "200": { "description": "Context updated" }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/context/data": { "patch": { "tags": [ "instances" ], "operationId": "patch_context_data", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchContextDataRequest" } } }, "required": true }, "responses": { "200": { "description": "Data patch applied without replacing other context sections" }, "400": { "description": "Existing data is not an object" }, "404": { "description": "Instance not found" }, "409": { "description": "Concurrent context updates; retry the request" }, "413": { "description": "Merged context exceeds its size limit" } } } }, "/instances/{id}/diagnosis": { "get": { "tags": [ "instances" ], "operationId": "get_diagnosis", "parameters": [ { "name": "id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Ranked diagnosis of why the instance is not progressing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceDiagnosisReport" } } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/effects": { "get": { "tags": [ "continuity" ], "operationId": "list_instance_effects", "responses": { "default": { "description": "Continuity API response" } } } }, "/instances/{id}/explain": { "get": { "tags": [ "instances" ], "operationId": "get_explanation", "parameters": [ { "name": "id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "llm", "in": "query", "description": "Attach an LLM-written narrative. Evidence is redacted with the platform RedactionPolicy before it is sent; the structured fields stay template-based. Provider/model/key come from ORCH8_EXPLAIN_LLM_PROVIDER / _MODEL / _API_KEY.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Plain-language explanation with likely cause, evidence, and suggested fix", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceExplanation" } } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/fork": { "post": { "tags": [ "instances" ], "operationId": "fork_instance", "parameters": [ { "name": "id", "in": "path", "description": "Source instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkRequest" } } }, "required": true }, "responses": { "201": { "description": "Fork created and scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkResponse" } } } }, "400": { "description": "Unknown block or invalid context patch" }, "404": { "description": "Instance or sequence not found" } } } }, "/instances/{id}/fork-preview": { "get": { "tags": [ "instances" ], "operationId": "fork_preview", "parameters": [ { "name": "id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from_block_id", "in": "query", "description": "Fork point", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "What a fork from this block would do — nothing is mutated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkPreview" } } } }, "400": { "description": "Block is not a top-level block of the sequence" }, "404": { "description": "Instance or block not found" } } } }, "/instances/{id}/inject-blocks": { "post": { "tags": [ "crate::instances" ], "operationId": "inject_blocks", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InjectBlocksRequest" } } }, "required": true }, "responses": { "200": { "description": "Blocks injected" } } } }, "/instances/{id}/logs": { "get": { "tags": [ "instances" ], "operationId": "get_instance_logs", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Step logs (oldest first)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StepLog" } } } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/outputs": { "get": { "tags": [ "instances" ], "operationId": "get_outputs", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Block outputs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BlockOutput" } } } } } } } }, "/instances/{id}/receipts/export": { "get": { "tags": [ "receipts" ], "summary": "Export the effect-receipt ledger of one instance as a signed JSONL bundle.", "operationId": "export_instance_receipts", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers only)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed JSONL bundle: header, one line per effect receipt, signature trailer. At-most-once dispatch evidence, not an exactly-once claim.", "content": { "application/x-ndjson": { "schema": { "type": "string" } } } }, "404": { "description": "Instance not found" }, "503": { "description": "Signing key not configured" } } } }, "/instances/{id}/remediations": { "get": { "tags": [ "instances" ], "operationId": "preview_remediations", "parameters": [ { "name": "id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "State-bound remediation previews", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RemediationPreview" } } } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/remediations/apply": { "post": { "tags": [ "instances" ], "operationId": "apply_remediation", "parameters": [ { "name": "id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyRemediationRequest" } } }, "required": true }, "responses": { "200": { "description": "Post-action remediation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemediationApplyEvidence" } } } }, "400": { "description": "Stale, manual, or unacknowledged remediation" }, "404": { "description": "Instance or preview not found" } } } }, "/instances/{id}/resume-from/{block_id}": { "post": { "tags": [ "instances" ], "summary": "DLQ surgery: re-run an instance from an arbitrary block.", "description": "Wipes the target block's outputs and the outputs of every block at or\nafter it in the sequence's top-level `blocks` array (including blocks\nnested inside wiped composites), optionally shallow-merges a context\npatch into `context.data`, and re-schedules the instance immediately.\nEarlier blocks keep their outputs: on the flat all-step execution path\nthe completed-blocks check skips them, so side-effectful handlers do not\nrun twice. On the tree path the execution tree is rebuilt from scratch —\nthe exact same semantics as `POST /instances/{id}/retry`, which also\ndeletes the tree while preserving real outputs.\n\nLinear assumption: \"after\" is defined by position in the top-level\n`blocks` array, which is the order both execution paths (flat fast path\nand tree evaluator) run top-level blocks in. The target must itself be a\ntop-level block — resuming from a block nested inside a composite is not\nsupported.", "operationId": "resume_from_block", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "block_id", "in": "path", "description": "Top-level block to resume from", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ResumeFromRequest" }, { "type": "null" } ] } } } }, "responses": { "200": { "description": "Instance re-scheduled from the given block", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Unknown block, or instance is in a state that cannot be resumed" }, "404": { "description": "Instance or sequence not found" } } } }, "/instances/{id}/retry": { "post": { "tags": [ "instances" ], "summary": "Retry a failed instance: reset to scheduled with immediate fire time.", "operationId": "retry_instance", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Instance retried", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Instance is not in failed state" }, "404": { "description": "Instance not found" }, "409": { "description": "Instance state changed concurrently" } } } }, "/instances/{id}/share": { "post": { "tags": [ "instances" ], "operationId": "create_share", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareRequest" } } }, "required": true }, "responses": { "201": { "description": "Share created; token returned once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareResponse" } } } }, "400": { "description": "Invalid expiry or field allowlist" }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/share/{share_id}": { "delete": { "tags": [ "instances" ], "operationId": "revoke_share", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "share_id", "in": "path", "description": "Share ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Share revoked" }, "404": { "description": "Unknown, foreign, or already-revoked share" } } } }, "/instances/{id}/shares": { "get": { "tags": [ "instances" ], "operationId": "list_shares", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Shares for the instance (tokens are never returned)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProgressShare" } } } } } } } }, "/instances/{id}/signals": { "post": { "tags": [ "instances" ], "operationId": "send_signal", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSignalRequest" } } }, "required": true }, "responses": { "201": { "description": "Signal enqueued", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Instance is in terminal state" }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/state": { "patch": { "tags": [ "instances" ], "operationId": "update_state", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStateRequest" } } }, "required": true }, "responses": { "200": { "description": "State updated" }, "400": { "description": "Invalid state transition" }, "404": { "description": "Instance not found" }, "409": { "description": "Instance state changed concurrently" } } } }, "/instances/{id}/stream": { "get": { "tags": [ "instances" ], "summary": "SSE stream for instance progress.", "operationId": "stream_instance", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "poll_ms", "in": "query", "description": "Poll interval in ms (min 100ms)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Server-Sent Events stream of instance state/output changes plus live llm_delta events from streaming llm_call steps", "content": { "text/event-stream": {} } }, "404": { "description": "Instance not found" }, "429": { "description": "Per-tenant concurrent stream limit reached" }, "503": { "description": "Too many concurrent streams" } } } }, "/instances/{id}/timeline": { "get": { "tags": [ "instances" ], "operationId": "get_timeline", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "description": "Pagination offset over executed-block entries", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Page size (default 200, max 1000)", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "include_outputs", "in": "query", "description": "Include output payloads and current context (default true)", "required": true, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Execution timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineResponse" } } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/tree": { "get": { "tags": [ "instances" ], "operationId": "get_execution_tree", "parameters": [ { "name": "id", "in": "path", "description": "Instance ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Execution tree", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionNode" } } } } }, "404": { "description": "Instance not found" } } } }, "/instances/{id}/workbench": { "get": { "tags": [ "instances" ], "operationId": "get_workbench", "parameters": [ { "name": "id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Max timeline events (default 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Joined, redacted execution view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionWorkbenchView" } } } }, "404": { "description": "Instance not found" } } } }, "/jobs": { "get": { "tags": [ "jobs" ], "summary": "List jobs, newest first, with keyset pagination.", "operationId": "list_jobs", "parameters": [ { "name": "handler", "in": "query", "description": "Only jobs for this handler", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "scheduled | running | completed | failed | cancelled | dead_lettered", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 50, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque `next_cursor` from the previous page", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "description": "Tenant filter (admin callers without X-Tenant-Id only)", "required": false, "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "description": "Namespace filter", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPage" } } } }, "400": { "description": "Invalid status or cursor" } } }, "post": { "tags": [ "jobs" ], "summary": "Enqueue a background job.", "operationId": "enqueue_job", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueJobRequest" } } }, "required": true }, "responses": { "200": { "description": "Idempotent replay: existing job returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "201": { "description": "Job enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid request" }, "413": { "description": "Payload exceeds the context size limit" } } } }, "/jobs/{id}": { "get": { "tags": [ "jobs" ], "summary": "Fetch one job.", "operationId": "get_job", "parameters": [ { "name": "id", "in": "path", "description": "Job id (= instance id)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "404": { "description": "Job not found" } } }, "delete": { "tags": [ "jobs" ], "summary": "Cancel a job. The cancel is a durable signal the engine applies promptly\n(202) -- saga compensations and `on_cancel` hooks run as part of it, so the\nreturned job may still show its pre-cancel status. Cancelling a job that\nalready finished is a 409.", "operationId": "cancel_job", "parameters": [ { "name": "id", "in": "path", "description": "Job id (= instance id)", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Cancellation requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "404": { "description": "Job not found" }, "409": { "description": "Job already finished" } } } }, "/license": { "get": { "tags": [ "license" ], "operationId": "get_license", "responses": { "200": { "description": "Offline-verified license status (soft enforcement only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseInfo" } } } } } } }, "/llm-cache": { "delete": { "tags": [ "usage" ], "operationId": "purge_llm_cache", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant (admin/unscoped callers only)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entries removed: {\"deleted\": n}", "content": { "application/json": { "schema": {} } } }, "400": { "description": "No tenant resolvable" } } } }, "/migrations/import": { "post": { "tags": [ "migrations" ], "summary": "Import a migration batch.", "operationId": "import", "requestBody": { "description": "MigrationImportRequest: { migration_id, source_engine_id, sequences: [SequenceDefinition], instances: [{ instance, execution_tree, block_outputs, effect_receipts, pending_signals, continuity }] } (at most 100 instances and 500 sequences)", "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "MigrationImportResponse: per-instance status (`imported` | `already_present`), owned epoch, and the target runtime id", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid batch (limits, unknown sequence, inconsistent ids)" }, "403": { "description": "Batch contains another tenant's records" }, "409": { "description": "An instance id exists but was not created by this migration" } } } }, "/placement/policies": { "get": { "tags": [ "placement" ], "operationId": "get_policies", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant (root key only; defaults to the X-Tenant-Id principal)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The tenant's placement policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacementPolicies" } } } } } }, "put": { "tags": [ "placement" ], "operationId": "put_policies", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant (root key only; defaults to the X-Tenant-Id principal)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacementPolicies" } } }, "required": true }, "responses": { "200": { "description": "Policies replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacementPolicies" } } } }, "400": { "description": "Invalid policies" } } } }, "/pools": { "get": { "tags": [ "pools" ], "operationId": "list_pools", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResourcePool" } } } } } } }, "post": { "tags": [ "pools" ], "operationId": "create_pool", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePoolRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePool" } } } } } } }, "/pools/{id}": { "get": { "tags": [ "pools" ], "operationId": "get_pool", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePool" } } } } } }, "delete": { "tags": [ "pools" ], "operationId": "delete_pool", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": {} } } }, "/pools/{pool_id}/resources": { "get": { "tags": [ "pools" ], "operationId": "list_resources", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PoolResource" } } } } } } }, "post": { "tags": [ "pools" ], "operationId": "add_resource", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddResourceRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolResource" } } } } } } }, "/pools/{pool_id}/resources/{resource_id}": { "put": { "tags": [ "pools" ], "operationId": "update_resource", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResourceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolResource" } } } } } }, "delete": { "tags": [ "pools" ], "operationId": "delete_resource", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": {} } } }, "/prompts": { "get": { "tags": [ "prompts" ], "operationId": "list_prompts", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PromptSummary" } } } } } } }, "post": { "tags": [ "prompts" ], "operationId": "push_prompt", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushPromptRequest" } } }, "required": true }, "responses": { "200": { "description": "Identical to the latest version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushPromptResponse" } } } }, "201": { "description": "New version created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushPromptResponse" } } } }, "400": { "description": "Invalid prompt" } } } }, "/prompts/{name}": { "get": { "tags": [ "prompts" ], "operationId": "get_prompt", "parameters": [ { "name": "name", "in": "path", "description": "Prompt name", "required": true, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptDetail" } } } }, "404": {} } } }, "/prompts/{name}/labels/{label}": { "put": { "tags": [ "prompts" ], "operationId": "set_prompt_label", "parameters": [ { "name": "name", "in": "path", "description": "Prompt name", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "path", "description": "Label, e.g. production", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetLabelRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptLabel" } } } }, "400": {}, "404": {} } }, "delete": { "tags": [ "prompts" ], "operationId": "delete_prompt_label", "parameters": [ { "name": "name", "in": "path", "description": "Prompt name", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "path", "description": "Label", "required": true, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers)", "required": false, "schema": { "type": "string" } } ], "responses": { "204": {}, "404": {} } } }, "/prompts/{name}/resolve": { "get": { "tags": [ "prompts" ], "operationId": "resolve_prompt", "parameters": [ { "name": "name", "in": "path", "description": "Prompt name", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "query", "description": "Resolve through this label (its stable version)", "required": false, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Exact version", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptTemplate" } } } }, "404": {} } } }, "/prompts/{name}/versions/{version}": { "get": { "tags": [ "prompts" ], "operationId": "get_prompt_version", "parameters": [ { "name": "name", "in": "path", "description": "Prompt name", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "description": "Version number", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptTemplate" } } } }, "404": {} } } }, "/public/progress/embed.js": { "get": { "tags": [ "public" ], "operationId": "embed_loader", "responses": { "200": { "description": "Embed loader script", "content": { "application/javascript": {} } } } } }, "/public/progress/{token}": { "get": { "tags": [ "public" ], "operationId": "public_progress", "parameters": [ { "name": "token", "in": "path", "description": "Share token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Redacted progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProgress" } } } }, "404": { "description": "Unknown, expired, or revoked link" }, "429": { "description": "Rate limited" } } } }, "/public/progress/{token}/embed": { "get": { "tags": [ "public" ], "operationId": "embed_page", "parameters": [ { "name": "token", "in": "path", "description": "Share token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Self-contained progress-bar page", "content": { "text/html": {} } }, "404": { "description": "Unknown, expired, or revoked link" } } } }, "/queues/dispatch": { "get": { "tags": [ "routing" ], "operationId": "list_dispatch", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dispatch configs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QueueDispatchConfig" } } } } } } }, "post": { "tags": [ "routing" ], "operationId": "set_dispatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDispatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Dispatch config set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueDispatchConfig" } } } }, "400": { "description": "push mode requires push_url" } } } }, "/queues/dispatch/{tenant_id}/{queue_name}": { "delete": { "tags": [ "routing" ], "operationId": "delete_dispatch", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant id", "required": true, "schema": { "type": "string" } }, { "name": "queue_name", "in": "path", "description": "Queue name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/rate-budgets": { "get": { "tags": [ "placement" ], "operationId": "list_budgets", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant (root key only)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The tenant's rate budgets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateBudgetList" } } } } } } }, "/rate-budgets/{key}": { "put": { "tags": [ "placement" ], "operationId": "put_budget", "parameters": [ { "name": "key", "in": "path", "description": "Budget key, e.g. `stripe-api`", "required": true, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (root key only)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateBudgetRequest" } } }, "required": true }, "responses": { "200": { "description": "Budget created (full) or reshaped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateBudget" } } } }, "400": { "description": "Invalid key or bucket parameters" } } }, "delete": { "tags": [ "placement" ], "operationId": "delete_budget", "parameters": [ { "name": "key", "in": "path", "description": "Budget key", "required": true, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (root key only)", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/receipts/export": { "get": { "tags": [ "receipts" ], "summary": "Export every effect receipt created in `[from, to)` for a tenant.", "operationId": "export_window_receipts", "parameters": [ { "name": "from", "in": "query", "description": "Window start (RFC 3339, inclusive)", "required": true, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Window end (RFC 3339, exclusive)", "required": true, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "description": "Tenant (unscoped callers only)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed JSONL bundle for the window. `scope.truncated=true` when more than 10000 instances were touched in the window.", "content": { "application/x-ndjson": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid window or missing tenant" }, "503": { "description": "Signing key not configured" } } } }, "/receipts/signing-key": { "get": { "tags": [ "receipts" ], "summary": "The public half of the key that signs receipt bundles.", "operationId": "signing_key", "responses": { "200": { "description": "Engine receipt-signing public key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyResponse" } } } }, "503": { "description": "Signing key not configured" } } } }, "/releases": { "get": { "tags": [ "releases" ], "operationId": "list_releases", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows (default 100)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Releases, newest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRelease" } } } } } } }, "post": { "tags": [ "releases" ], "operationId": "create_release", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReleaseRequest" } } }, "required": true }, "responses": { "201": { "description": "Release created (draft)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRelease" } } } }, "400": { "description": "Baseline/candidate mismatch" }, "404": { "description": "Sequence not found" } } } }, "/releases/{id}": { "get": { "tags": [ "releases" ], "operationId": "get_release", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRelease" } } } }, "404": { "description": "Not found" } } } }, "/releases/{id}/canary": { "post": { "tags": [ "releases" ], "operationId": "start_canary", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanaryRequest" } } }, "required": true }, "responses": { "200": { "description": "Canary started/resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRelease" } } } }, "409": { "description": "Release is not ready/paused" } } } }, "/releases/{id}/decisions": { "get": { "tags": [ "releases" ], "operationId": "list_decisions", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Immutable audit trail, oldest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseDecision" } } } } } } } }, "/releases/{id}/diff": { "get": { "tags": [ "releases" ], "operationId": "diff_release", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Semantic diff of this release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticDiff" } } } } } } }, "/releases/{id}/evaluate": { "post": { "tags": [ "releases" ], "operationId": "evaluate_release", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Gate evaluation; a failing gate during canary rolls the release back automatically (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationReport" } } } } } } }, "/releases/{id}/pause": { "post": { "tags": [ "releases" ], "operationId": "pause_release", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Paused (traffic returns to baseline)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRelease" } } } } } } }, "/releases/{id}/promote": { "post": { "tags": [ "releases" ], "operationId": "promote_release", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteRequest" } } }, "required": true }, "responses": { "200": { "description": "Promoted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRelease" } } } }, "409": { "description": "Gates not passing (pass force=true to override)" } } } }, "/releases/{id}/rollback": { "post": { "tags": [ "releases" ], "operationId": "rollback_release", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rolled back — all new traffic returns to the baseline. Idempotent: rolling back an already rolled-back release is a no-op.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRelease" } } } } } } }, "/releases/{id}/target": { "put": { "tags": [ "releases" ], "operationId": "set_release_target", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Sub-tenant rollout target, or null to return to per-instance cohorts", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ReleaseTarget" }, { "type": "null" } ] } } } }, "responses": { "200": { "description": "Target replaced (audited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRelease" } } } }, "400": { "description": "Invalid target" }, "409": { "description": "Release is promoted or rolled back" } } } }, "/releases/{id}/validate": { "post": { "tags": [ "releases" ], "operationId": "validate_release", "parameters": [ { "name": "id", "in": "path", "description": "Release id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateRequest" } } }, "required": true }, "responses": { "200": { "description": "Validation report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationReport" } } } }, "409": { "description": "Release is not in draft" } } } }, "/routing-rules": { "get": { "tags": [ "routing" ], "operationId": "list_rules", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } }, { "name": "handler_name", "in": "query", "description": "Filter by handler", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Routing rules", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QueueRoutingRule" } } } } } } }, "post": { "tags": [ "routing" ], "operationId": "create_rule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingRuleRequest" } } }, "required": true }, "responses": { "201": { "description": "Rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueRoutingRule" } } } }, "400": { "description": "Missing/empty fields" } } } }, "/routing-rules/{id}": { "get": { "tags": [ "routing" ], "operationId": "get_rule", "parameters": [ { "name": "id", "in": "path", "description": "Rule id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueRoutingRule" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "routing" ], "operationId": "delete_rule", "parameters": [ { "name": "id", "in": "path", "description": "Rule id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/runtimes": { "get": { "tags": [ "continuity" ], "description": "List the tenant's live runtime advertisements (`RuntimeCapabilities`). A device-session (`dst_`) caller receives only the runtimes it could delegate to now — other than itself, not draining, not expired, at least `registered` trust, advertising `orch8.delegation` — reduced to `runtime_id`, `kind`, `handlers`, `observed_at` and `expires_at`, with `trust` reported as `registered` and every other fact omitted.", "operationId": "list_runtimes", "responses": { "default": { "description": "Continuity API response" } } } }, "/runtimes/browser-sessions": { "post": { "tags": [ "workers" ], "summary": "Mint a browser-session token. Operator/Admin only — called by the\ncustomer's app backend, never by the browser itself.", "operationId": "create_browser_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrowserSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "Scoped browser-session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrowserSessionResponse" } } } }, "400": { "description": "Invalid handlers, queues, or ttl" }, "403": { "description": "Caller is not an operator" } } } }, "/runtimes/device-sessions": { "post": { "tags": [ "workers" ], "summary": "Mint a device-session token. Operator/Admin only — called by the\ncustomer's app backend, never by the phone itself.", "operationId": "create_device_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeviceSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "Scoped device-session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeviceSessionResponse" } } } }, "400": { "description": "Invalid device_id, handlers, or ttl" }, "403": { "description": "Caller is not an operator" }, "409": { "description": "The device is registered to another tenant" } } } }, "/runtimes/register": { "post": { "tags": [ "continuity" ], "operationId": "register_runtime", "responses": { "default": { "description": "Continuity API response" } } } }, "/sequences": { "get": { "tags": [ "sequences" ], "operationId": "list_sequences", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Optional tenant filter", "required": false, "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "description": "Optional namespace filter", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows (default 200, max 1000)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "All sequences (filtered/paginated)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceDefinition" } } } } } } }, "post": { "tags": [ "sequences" ], "operationId": "create_sequence", "requestBody": { "description": "Sequence definition as JSON, or as YAML with `Content-Type: application/yaml`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceDefinition" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SequenceDefinition" } } }, "required": true }, "responses": { "201": { "description": "Sequence created", "content": { "application/json": { "schema": {} } } }, "409": { "description": "Sequence already exists" } } } }, "/sequences/by-name": { "get": { "tags": [ "sequences" ], "operationId": "get_sequence_by_name", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant ID", "required": true, "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "description": "Namespace", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Sequence name", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Optional version", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Sequence found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceDefinition" } } } }, "404": { "description": "Sequence not found" } } } }, "/sequences/dataflow": { "post": { "tags": [ "sequences" ], "operationId": "compile_draft", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceDefinition" } } }, "required": true }, "responses": { "200": { "description": "Typed dataflow report and deterministic bindings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataflowResponse" } } } }, "400": { "description": "Invalid sequence or generation bounds exceeded" } } } }, "/sequences/inspect-template": { "post": { "tags": [ "sequences" ], "operationId": "inspect_draft", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "Resolution trace for the block's params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionTrace" } } } }, "400": { "description": "Invalid request" }, "404": { "description": "Sequence or block not found" } } } }, "/sequences/migrate-instance": { "post": { "tags": [ "sequences" ], "operationId": "migrate_instance", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrateInstanceRequest" } } }, "required": true }, "responses": { "200": { "description": "Instance migrated to new sequence version" }, "400": { "description": "Instance in terminal state" }, "404": { "description": "Instance or sequence not found" }, "409": { "description": "Target sequence is structurally incompatible with the instance's execution state" } } } }, "/sequences/preflight": { "post": { "tags": [ "sequences" ], "operationId": "preflight_draft", "requestBody": { "description": "Draft definition as JSON, or as YAML with `Content-Type: application/yaml`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceDefinition" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/SequenceDefinition" } } }, "required": true }, "responses": { "200": { "description": "Preflight report for the draft definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightReport" } } } }, "400": { "description": "Body is not a sequence definition" } } } }, "/sequences/releases/diff": { "post": { "tags": [ "releases" ], "operationId": "diff_sequences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiffRequest" } } }, "required": true }, "responses": { "200": { "description": "Semantic diff report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticDiff" } } } }, "404": { "description": "Sequence not found" } } } }, "/sequences/versions": { "get": { "tags": [ "sequences" ], "operationId": "list_sequence_versions", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant ID", "required": true, "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "description": "Namespace", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Sequence name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All versions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceDefinition" } } } } } } } }, "/sequences/{id}": { "get": { "tags": [ "sequences" ], "operationId": "get_sequence", "parameters": [ { "name": "id", "in": "path", "description": "Sequence ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sequence found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceDefinition" } } } }, "404": { "description": "Sequence not found" } } } }, "/sequences/{id}/dataflow": { "get": { "tags": [ "sequences" ], "operationId": "compile_stored", "parameters": [ { "name": "id", "in": "path", "description": "Sequence id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Typed dataflow report and deterministic bindings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataflowResponse" } } } }, "404": { "description": "Sequence not found" } } } }, "/sequences/{id}/deprecate": { "post": { "tags": [ "sequences" ], "operationId": "deprecate_sequence", "parameters": [ { "name": "id", "in": "path", "description": "Sequence ID to deprecate", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Sequence deprecated" } } } }, "/sequences/{id}/preflight": { "get": { "tags": [ "sequences" ], "operationId": "preflight_stored", "parameters": [ { "name": "id", "in": "path", "description": "Sequence id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Preflight report for the stored sequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightReport" } } } }, "404": { "description": "Sequence not found" } } } }, "/sessions": { "post": { "tags": [ "crate::sessions" ], "operationId": "create_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } } } } }, "/sessions/by-key/{tenant_id}/{key}": { "get": { "tags": [ "crate::sessions" ], "operationId": "get_session_by_key", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant ID", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Session key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } } } } }, "/sessions/{id}": { "get": { "tags": [ "crate::sessions" ], "operationId": "get_session", "parameters": [ { "name": "id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } } } } }, "/sessions/{id}/data": { "patch": { "tags": [ "crate::sessions" ], "operationId": "update_session_data", "parameters": [ { "name": "id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionDataRequest" } } }, "required": true }, "responses": { "200": { "description": "Session data updated" } } } }, "/sessions/{id}/instances": { "get": { "tags": [ "crate::sessions" ], "operationId": "list_session_instances", "parameters": [ { "name": "id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaskInstance" } } } } } } } }, "/sessions/{id}/state": { "patch": { "tags": [ "crate::sessions" ], "operationId": "update_session_state", "parameters": [ { "name": "id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionStateRequest" } } }, "required": true }, "responses": { "200": { "description": "Session state updated" } } } }, "/sub-tenants/{sub}/limits": { "get": { "tags": [ "sub-tenants" ], "operationId": "get_sub_tenant_limits", "parameters": [ { "name": "sub", "in": "path", "description": "Sub-tenant id ([A-Za-z0-9._:-]{1,128})", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Caps (null = uncapped; unset sub-tenants are uncapped)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubTenantLimitsResponse" } } } }, "400": { "description": "Invalid sub-tenant id or no tenant" } } }, "put": { "tags": [ "sub-tenants" ], "operationId": "put_sub_tenant_limits", "parameters": [ { "name": "sub", "in": "path", "description": "Sub-tenant id ([A-Za-z0-9._:-]{1,128})", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubTenantLimits" } } }, "required": true }, "responses": { "200": { "description": "Caps replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubTenantLimitsResponse" } } } }, "400": { "description": "Invalid sub-tenant id, body or no tenant" } } } }, "/sub-tenants/{sub}/resume": { "post": { "tags": [ "sub-tenants" ], "operationId": "resume_sub_tenant", "parameters": [ { "name": "sub", "in": "path", "description": "Sub-tenant id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Embed tokens of the sub-tenant are accepted again" }, "403": { "description": "Operator capability required" } } } }, "/sub-tenants/{sub}/suspend": { "post": { "tags": [ "sub-tenants" ], "operationId": "suspend_sub_tenant", "parameters": [ { "name": "sub", "in": "path", "description": "Sub-tenant id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Every embed token of the sub-tenant is refused (401) within a few seconds" }, "403": { "description": "Operator capability required" } } } }, "/tenants/{tenant_id}/circuit-breakers": { "get": { "tags": [ "crate::circuit_breakers" ], "operationId": "list_breakers_for_tenant", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CircuitBreakerState" } } } } } } } }, "/tenants/{tenant_id}/circuit-breakers/{handler}": { "get": { "tags": [ "crate::circuit_breakers" ], "operationId": "get_breaker", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant id", "required": true, "schema": { "type": "string" } }, { "name": "handler", "in": "path", "description": "Handler name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CircuitBreakerState" } } } }, "404": { "description": "Handler not found" } } } }, "/tenants/{tenant_id}/circuit-breakers/{handler}/reset": { "post": { "tags": [ "crate::circuit_breakers" ], "operationId": "reset_breaker", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant id", "required": true, "schema": { "type": "string" } }, { "name": "handler", "in": "path", "description": "Handler name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Circuit breaker reset" } } } }, "/triggers": { "get": { "tags": [ "triggers" ], "operationId": "list_triggers", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Triggers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerDef" } } } } } } }, "post": { "tags": [ "triggers" ], "operationId": "create_trigger", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTriggerRequest" } } }, "required": true }, "responses": { "201": { "description": "Trigger created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerDef" } } } }, "400": { "description": "Invalid input" } } } }, "/triggers/{slug}": { "get": { "tags": [ "triggers" ], "operationId": "get_trigger", "parameters": [ { "name": "slug", "in": "path", "description": "Trigger slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trigger. For activepieces_poll triggers the response additionally carries a `poll_state` field (cursor, last_error, consecutive_failures, last_poll_at).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerDef" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "triggers" ], "operationId": "delete_trigger", "parameters": [ { "name": "slug", "in": "path", "description": "Trigger slug", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/triggers/{slug}/fire": { "post": { "tags": [ "triggers" ], "summary": "Fire a trigger: create a new instance from the trigger's sequence.", "description": "The request body becomes the initial `context.data` for the instance.", "operationId": "fire_trigger", "parameters": [ { "name": "slug", "in": "path", "description": "Trigger slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "201": { "description": "Instance created" }, "400": { "description": "Trigger disabled or bad secret" }, "404": { "description": "Not found" } } } }, "/triggers/{slug}/target": { "patch": { "tags": [ "triggers" ], "operationId": "retarget_trigger", "parameters": [ { "name": "slug", "in": "path", "description": "Trigger slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetargetTriggerRequest" } } }, "required": true }, "responses": { "204": { "description": "Trigger target updated; credentials and settings preserved" }, "404": { "description": "Trigger or sequence not found" }, "409": { "description": "Trigger changed concurrently or sequence name/version is ambiguous" } } } }, "/usage": { "get": { "tags": [ "usage" ], "operationId": "get_usage", "parameters": [ { "name": "tenant", "in": "query", "description": "Tenant (admin/unscoped callers only)", "required": false, "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Window start (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "Window end (RFC 3339)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage aggregated by (kind, model) with estimated USD costs, cache savings and current budget status", "content": { "application/json": { "schema": {} } } }, "400": { "description": "No tenant resolvable" } } } }, "/usage/sub-tenants": { "get": { "tags": [ "sub-tenants" ], "operationId": "get_sub_tenant_usage", "parameters": [ { "name": "from", "in": "query", "description": "Window start (RFC 3339, inclusive). Defaults to the start of the\ncurrent UTC month.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "description": "Window end (RFC 3339, exclusive). Defaults to now.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } } ], "responses": { "200": { "description": "Per-sub-tenant activity in [from, to)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubTenantUsageResponse" } } } }, "400": { "description": "Invalid window or no tenant" } } } }, "/webhooks/deliveries": { "get": { "tags": [ "webhooks" ], "operationId": "list_deliveries", "parameters": [ { "name": "url", "in": "query", "description": "Filter by endpoint URL", "required": false, "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "description": "Filter by event type", "required": false, "schema": { "type": "string" } }, { "name": "delivered", "in": "query", "description": "true = delivered, false = failed", "required": false, "schema": { "type": "boolean" } }, { "name": "error_class", "in": "query", "description": "Final-attempt error class", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows (default 100, max 1000)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Delivery summaries, newest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliverySummary" } } } } } } } }, "/webhooks/deliveries/{delivery_id}": { "get": { "tags": [ "webhooks" ], "operationId": "get_delivery", "parameters": [ { "name": "delivery_id", "in": "path", "description": "Delivery (attempt group) id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Attempt timeline for one delivery", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryAttempt" } } } } }, "404": { "description": "No attempts recorded for this delivery" } } } }, "/webhooks/outbox": { "get": { "tags": [ "webhooks" ], "operationId": "list_outbox", "parameters": [ { "name": "limit", "in": "query", "description": "Max rows (default 100, max 1000)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Parked webhook deliveries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookOutboxEntry" } } } } } } } }, "/webhooks/outbox/{id}": { "delete": { "tags": [ "webhooks" ], "operationId": "discard_outbox", "parameters": [ { "name": "id", "in": "path", "description": "Parked delivery id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Discarded" } } } }, "/webhooks/outbox/{id}/redeliver": { "post": { "tags": [ "webhooks" ], "operationId": "redeliver_outbox", "parameters": [ { "name": "id", "in": "path", "description": "Parked delivery id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Redelivered (row removed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeliverResponse" } } } }, "404": { "description": "No such parked delivery" }, "409": { "description": "Delivery is pending or already claimed by the scheduler" }, "502": { "description": "Redelivery failed (row kept)" } } } }, "/webhooks/outbox/{id}/redeliver-preview": { "get": { "tags": [ "webhooks" ], "operationId": "redeliver_preview", "parameters": [ { "name": "id", "in": "path", "description": "Parked delivery id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "What a redelivery would send (no side effect)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeliverPreview" } } } }, "404": { "description": "No such parked delivery" } } } }, "/webhooks/{slug}": { "post": { "tags": [ "webhooks" ], "summary": "Accept an inbound webhook POST and create a new instance from its body.", "description": "Rejects with 404 if:\n- The slug doesn't exist.\n- The trigger is disabled.\n- The trigger is not of type `webhook` (events and nats are internal only).\n\nRejects with 401 if:\n- The trigger has no secret, or the request signature is missing/invalid.", "operationId": "public_webhook", "parameters": [ { "name": "slug", "in": "path", "description": "Webhook slug (the trigger slug)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "202": { "description": "Webhook accepted; instance created and queued for execution" }, "401": { "description": "Missing or invalid webhook signature" }, "404": { "description": "Unknown slug, disabled trigger, or non-webhook trigger type" } } } }, "/workers": { "get": { "tags": [ "workers" ], "operationId": "list_workers", "parameters": [ { "name": "alive_within_secs", "in": "query", "description": "Liveness window in seconds (default 60)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_stale", "in": "query", "description": "Include workers not seen within the window", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Worker fleet with liveness", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkerInfo" } } } } } } } }, "/workers/commands": { "post": { "tags": [ "workers" ], "summary": "Queue a control command for a worker. The worker picks it up via\n`GET /workers/{worker_id}/commands` and acks it after acting.", "description": "This is an operator/admin endpoint: only callers with an admin context may\nenqueue commands to the worker fleet.", "operationId": "enqueue_command", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueCommandRequest" } } }, "required": true }, "responses": { "201": { "description": "Command queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkerCommand" } } } }, "403": { "description": "Admin context required" } } } }, "/workers/commands/{id}": { "delete": { "tags": [ "workers" ], "summary": "Acknowledge (delete) a delivered command.", "operationId": "ack_command", "parameters": [ { "name": "id", "in": "path", "description": "Command id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Acknowledged" } } } }, "/workers/tasks": { "get": { "tags": [ "workers" ], "operationId": "list_tasks", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Comma-separated worker task states", "required": false, "schema": { "type": "string" } }, { "name": "handler_name", "in": "query", "description": "Filter by handler name", "required": false, "schema": { "type": "string" } }, { "name": "worker_id", "in": "query", "description": "Filter by claiming worker id", "required": false, "schema": { "type": "string" } }, { "name": "queue_name", "in": "query", "description": "Filter by queue name", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows to return (≤ 1000)", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skip N rows", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Worker tasks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkerTask" } } } } } } } }, "/workers/tasks/poll": { "post": { "tags": [ "workers" ], "operationId": "poll_tasks", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollRequest" } } }, "required": true }, "responses": { "200": { "description": "Claimed worker tasks and lease hints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollTasksResponse" } } } } } } }, "/workers/tasks/poll/queue": { "post": { "tags": [ "workers" ], "operationId": "poll_tasks_from_queue", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuePollRequest" } } }, "required": true }, "responses": { "200": { "description": "Claimed worker tasks from queue and lease hints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollTasksResponse" } } } } } } }, "/workers/tasks/stats": { "get": { "tags": [ "workers" ], "operationId": "task_stats", "parameters": [ { "name": "window_secs", "in": "query", "description": "When set (1..=604800), `completed`/`failed` rows are counted only if finished within the last N seconds, so `by_handler` failure rates reflect a recent window; `pending`/`claimed` are live gauges and always counted. Omit for lifetime counts (default).", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Aggregate worker task stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkerTaskStats" } } } } } } }, "/workers/tasks/{id}/artifacts/{upload_id}": { "post": { "tags": [ "workers" ], "summary": "Upload a task-owned file before completion. The client chooses `upload_id`,\nso a phone can safely retry after suspension or a network transition.", "operationId": "upload_task_artifact", "parameters": [ { "name": "id", "in": "path", "description": "Worker task ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "upload_id", "in": "path", "description": "Stable client idempotency key", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "worker_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "claim_epoch", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "file_name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sha256", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "required": true }, "responses": { "201": { "description": "Artifact stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkerArtifactReceipt" } } } }, "409": { "description": "Lease changed or upload ID reused with other bytes" } } } }, "/workers/tasks/{id}/attempts": { "get": { "tags": [ "workers" ], "operationId": "list_task_attempts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkerTaskAttemptEvent" } } } } }, "404": {} } } }, "/workers/tasks/{id}/complete": { "post": { "tags": [ "workers" ], "operationId": "complete_task", "parameters": [ { "name": "id", "in": "path", "description": "Worker task ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteRequest" } } }, "required": true }, "responses": { "200": { "description": "Task completed" }, "404": { "description": "Worker task not found" } } } }, "/workers/tasks/{id}/fail": { "post": { "tags": [ "workers" ], "operationId": "fail_task", "parameters": [ { "name": "id", "in": "path", "description": "Worker task ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailRequest" } } }, "required": true }, "responses": { "200": { "description": "Task failed" }, "404": { "description": "Worker task not found" } } } }, "/workers/tasks/{id}/heartbeat": { "post": { "tags": [ "workers" ], "operationId": "heartbeat_task", "parameters": [ { "name": "id", "in": "path", "description": "Worker task ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatRequest" } } }, "required": true }, "responses": { "200": { "description": "Heartbeat/checkpoint updated; response contains checkpoint_seq" }, "404": { "description": "Worker task is not currently owned by this worker" }, "409": { "description": "Worker lost ownership or checkpoint sequence is stale" } } } }, "/workers/tasks/{id}/release": { "post": { "tags": [ "workers" ], "summary": "Voluntarily give a claimed task back (tab closing, app backgrounding).\nSafe to call from `fetch(url, {keepalive: true})` during `pagehide`.", "operationId": "release_task", "parameters": [ { "name": "id", "in": "path", "description": "Worker task ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseRequest" } } }, "required": true }, "responses": { "204": { "description": "Task released" }, "404": { "description": "Worker task not found" }, "409": { "description": "Caller no longer holds this lease (or ownership changed)" } } } }, "/workers/version-pins": { "get": { "tags": [ "workers" ], "summary": "List worker version pins, optionally filtered by tenant.", "operationId": "list_version_pins", "parameters": [ { "name": "tenant_id", "in": "query", "description": "Filter by tenant", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pins", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkerVersionPin" } } } } } } }, "post": { "tags": [ "workers" ], "summary": "Create-or-update a minimum-worker-version pin for a `(tenant, handler)`.", "operationId": "set_version_pin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetVersionPinRequest" } } }, "required": true }, "responses": { "200": { "description": "Pin set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkerVersionPin" } } } } } } }, "/workers/version-pins/{tenant_id}/{handler_name}": { "delete": { "tags": [ "workers" ], "summary": "Delete a worker version pin.", "operationId": "delete_version_pin", "parameters": [ { "name": "tenant_id", "in": "path", "description": "Tenant id", "required": true, "schema": { "type": "string" } }, { "name": "handler_name", "in": "path", "description": "Handler name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/workers/{worker_id}/commands": { "get": { "tags": [ "workers" ], "summary": "List a worker's pending control commands (the worker control channel).", "operationId": "list_commands", "parameters": [ { "name": "worker_id", "in": "path", "description": "Worker id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pending commands", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkerCommand" } } } } } } } } }, "components": { "schemas": { "ABSplitDef": { "type": "object", "description": "A/B split: deterministically route each instance to one of several\nweighted variants. The chosen variant is persisted in the block output\nso re-executions always follow the same path.", "required": [ "id", "variants" ], "properties": { "id": { "$ref": "#/components/schemas/BlockId" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ABVariant" }, "description": "Weighted variants. Weights are relative (e.g. 70 + 30 = 100%)." } } }, "ABVariant": { "type": "object", "description": "One arm of an A/B split.", "required": [ "name", "weight", "blocks" ], "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockDefinition" }, "description": "Blocks to execute when this variant is chosen." }, "name": { "type": "string", "description": "Human-readable label (e.g. \"control\", `\"variant_a\"`)." }, "weight": { "type": "integer", "format": "int32", "description": "Relative weight. Higher = more traffic.", "minimum": 0 } } }, "AddResourceRequest": { "type": "object", "required": [ "resource_key", "name" ], "properties": { "daily_cap": { "type": "integer", "format": "int32", "minimum": 0 }, "name": { "type": "string" }, "resource_key": { "type": "string" }, "warmup_days": { "type": "integer", "format": "int32", "minimum": 0 }, "warmup_start": { "type": [ "string", "null" ] }, "warmup_start_cap": { "type": "integer", "format": "int32", "minimum": 0 }, "weight": { "type": "integer", "format": "int32", "minimum": 0 } } }, "Affinity": { "type": "string", "description": "Sticky-affinity mode.", "enum": [ "instance", "none" ] }, "AlertCondition": { "oneOf": [ { "type": "object", "description": "Failed (dead-lettered) instances in the tenant. Fires when the total\nreaches `threshold`, or when at least `growth` new failures land\nwithin `window_secs`. At least one of the two must be set.", "required": [ "kind" ], "properties": { "growth": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "kind": { "type": "string", "enum": [ "dlq_growth" ] }, "threshold": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "window_secs": { "type": "integer", "format": "int64", "minimum": 0 } } }, { "type": "object", "description": "Any circuit breaker (or the named handler's) for the tenant is open.", "required": [ "kind" ], "properties": { "handler": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "circuit_breaker_opened" ] } } }, { "type": "object", "description": "Instances paused by budget enforcement (`paused_reason =\nbudget_exceeded`) reach `min_instances` (default 1).", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "budget_breach" ] }, "min_instances": { "type": "integer", "format": "int64", "minimum": 0 } } }, { "type": "object", "description": "No worker for `handler` (optionally on `queue`) has polled within\n`seen_within_secs`.", "required": [ "handler", "kind" ], "properties": { "handler": { "type": "string" }, "kind": { "type": "string", "enum": [ "worker_pool_empty" ] }, "queue": { "type": [ "string", "null" ] }, "seen_within_secs": { "type": "integer", "format": "int64", "minimum": 0 } } } ], "description": "What the evaluator watches." }, "AlertDestination": { "oneOf": [ { "type": "object", "description": "Slack incoming webhook; `url_ref` is `credentials://id[/field]`.", "required": [ "url_ref", "type" ], "properties": { "type": { "type": "string", "enum": [ "slack" ] }, "url_ref": { "type": "string" } } }, { "type": "object", "description": "`PagerDuty` Events API v2. `routing_key_ref` is a credential reference.\nFiring sends `trigger`, recovery sends `resolve` with the same\n`dedup_key`.", "required": [ "routing_key_ref", "type" ], "properties": { "routing_key_ref": { "type": "string" }, "severity": { "type": "string" }, "type": { "type": "string", "enum": [ "pagerduty" ] } } }, { "type": "object", "description": "Generic JSON webhook, HMAC-signed (`X-Orch8-Signature`) with the\nsecret behind `secret_ref`.", "required": [ "url", "secret_ref", "type" ], "properties": { "secret_ref": { "type": "string" }, "type": { "type": "string", "enum": [ "webhook" ] }, "url": { "type": "string" } } } ], "description": "Where a transition is delivered." }, "AlertRule": { "type": "object", "description": "A tenant-scoped alert rule.", "required": [ "id", "tenant_id", "name", "condition", "destination", "created_at", "updated_at" ], "properties": { "condition": { "$ref": "#/components/schemas/AlertCondition" }, "cooldown_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "destination": { "$ref": "#/components/schemas/AlertDestination" }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tenant_id": { "$ref": "#/components/schemas/TenantId" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AlertRuleRequest": { "type": "object", "required": [ "name", "condition", "destination" ], "properties": { "condition": { "$ref": "#/components/schemas/AlertCondition" }, "cooldown_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "destination": { "$ref": "#/components/schemas/AlertDestination" }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "tenant_id": { "type": "string", "description": "Tenant (defaults to the `X-Tenant-Id` header)." } } }, "AlertRuleState": { "type": "object", "description": "Evaluator bookkeeping for one rule, updated with a version CAS so that\nexactly one engine node emits each transition.", "required": [ "rule_id", "firing", "version" ], "properties": { "firing": { "type": "boolean" }, "last_evaluated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_fired_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_value": { "type": "number", "format": "double", "description": "Last observed metric value (DLQ count, open breakers, …)." }, "rule_id": { "type": "string", "format": "uuid" }, "samples": { "type": "array", "items": { "type": "array", "items": false, "prefixItems": [ { "type": "integer", "format": "int64" }, { "type": "number", "format": "double" } ] }, "description": "Rolling samples `(unix_secs, value)` for rate conditions." }, "version": { "type": "integer", "format": "int64", "description": "Monotonic CAS version (0 = never stored)." } } }, "AlertRuleView": { "allOf": [ { "$ref": "#/components/schemas/AlertRule" }, { "type": "object", "properties": { "state": { "oneOf": [ { "$ref": "#/components/schemas/AlertRuleState", "description": "Evaluator state (absent until first evaluation)." }, { "type": "null" } ] } } } ] }, "ApiCapability": { "type": "string", "description": "Coarse principal capabilities enforced before tenant API routing.", "enum": [ "operator", "worker", "device", "publisher", "approver", "auditor", "browser_worker", "device_node" ] }, "ApplyRemediationRequest": { "type": "object", "required": [ "preview_id" ], "properties": { "acknowledge_side_effect_risk": { "type": "boolean", "description": "Required for recipes which may repeat an external side effect." }, "preview_id": { "type": "string" } } }, "ArtifactRef": { "type": "object", "description": "A durable reference to stored bytes. Travels in step outputs / context as\n`{ \"artifact\": { ... } }` — never the bytes themselves.", "required": [ "id", "instance_id", "key", "content_type", "size", "uri" ], "properties": { "content_type": { "type": "string", "description": "MIME type captured at store time (e.g. `image/png`, `text/html`)." }, "id": { "type": "string", "description": "Opaque artifact id (unique within the instance)." }, "instance_id": { "type": "string", "description": "Owning instance — artifacts are instance-scoped (object keys are\nprefixed with it, so an instance's blobs can be enumerated via\n`list_artifacts` and removed via `delete_artifact`). Note: unlike DB\nrows, object-store blobs are not yet swept automatically on instance\ndeletion — that cleanup is a follow-up." }, "key": { "type": "string", "description": "Backend object key (e.g. `\"/\"`)." }, "size": { "type": "integer", "format": "int64", "description": "Size in bytes.", "minimum": 0 }, "uri": { "type": "string", "description": "Logical URI: `artifact://`." } } }, "AuditEntry": { "type": "object", "required": [ "timestamp", "event", "details" ], "properties": { "details": {}, "event": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "AuditLogEntry": { "type": "object", "description": "An immutable audit log entry recording a state transition or lifecycle event.", "required": [ "id", "instance_id", "tenant_id", "event_type", "created_at" ], "properties": { "block_id": { "type": [ "string", "null" ], "description": "Block ID related to this event, if any." }, "created_at": { "type": "string", "format": "date-time" }, "details": { "description": "Additional event data (e.g., error message, signal payload)." }, "event_type": { "type": "string", "description": "Event type (e.g. `state_transition`, `signal_received`, `step_completed`, `step_failed`)." }, "from_state": { "type": [ "string", "null" ], "description": "Previous state (for transitions)." }, "id": { "type": "string", "format": "uuid" }, "instance_id": { "$ref": "#/components/schemas/InstanceId" }, "tenant_id": { "$ref": "#/components/schemas/TenantId" }, "to_state": { "type": [ "string", "null" ], "description": "New state (for transitions)." } } }, "AutoDecideDef": { "type": "object", "description": "`wait_for_input.auto_decide`: let a calibrated decision model answer a\nhuman gate when it is confident enough.", "properties": { "api_key": { "type": [ "string", "null" ], "description": "API key (literal or `credentials://` reference). When omitted the\noperator's `TYPESAFE_API_KEY` is used — only for the default endpoint." }, "base_url": { "type": [ "string", "null" ], "description": "Endpoint override; requires an explicit `api_key`." }, "instructions": { "type": [ "string", "null" ], "description": "Question put to the model; defaults to the gate's `prompt`." }, "interpret_replies": { "type": "boolean", "description": "Map a free-text human reply (`{\"text\": \"sure, go ahead\"}`) onto one of\nthe gate's choices instead of rejecting it as an invalid value." }, "model": { "type": [ "string", "null" ], "description": "Model id; defaults to `jev-latest`." }, "threshold": { "type": "number", "format": "double", "description": "Minimum model confidence in `[0, 1]` to accept without a human." } } }, "BatchAction": { "type": "string", "description": "The operation a batch action applies to every matched instance.", "enum": [ "retry", "pause", "resume", "cancel", "signal" ] }, "BatchActionRequest": { "type": "object", "required": [ "filter", "action" ], "properties": { "action": { "$ref": "#/components/schemas/BatchAction" }, "dry_run": { "type": "boolean", "description": "When true, count matching instances and apply nothing." }, "filter": { "$ref": "#/components/schemas/BulkFilter" }, "limit": { "type": "integer", "format": "int32", "description": "Hard cap on how many instances are acted on. Default 1000, max 10000.", "minimum": 0 }, "payload": { "description": "Payload for the `signal` action." }, "signal_type": { "type": [ "string", "null" ], "description": "Custom signal name for the `signal` action (no `custom:` prefix). Ignored\nfor the other actions." } } }, "BatchActionResponse": { "type": "object", "required": [ "matched", "applied", "skipped", "failed", "dry_run" ], "properties": { "applied": { "type": "integer", "format": "int64", "description": "Instances the action was successfully applied to.", "minimum": 0 }, "dry_run": { "type": "boolean" }, "failed": { "type": "integer", "format": "int64", "description": "Instances where applying the action errored.", "minimum": 0 }, "matched": { "type": "integer", "format": "int64", "description": "Instances matched by the filter (capped by `limit`).", "minimum": 0 }, "skipped": { "type": "integer", "format": "int64", "description": "Instances the action did not apply to (e.g. retry of a non-Failed\ninstance, or a signal to a terminal instance).", "minimum": 0 } } }, "BatchCreateRequest": { "type": "object", "required": [ "instances" ], "properties": { "instances": { "type": "array", "items": { "$ref": "#/components/schemas/CreateInstanceRequest" } } } }, "BatchIngestRequest": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/IngestEventRequest" }, "description": "Events read from a transactional outbox. Retries are safe because each\nitem carries its producer idempotency identity." } } }, "BatchIngestResponse": { "type": "object", "required": [ "outcomes" ], "properties": { "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/IngestOutcome" } } } }, "BlockDefinition": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/StepDef" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "step" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ParallelDef" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "parallel" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/RaceDef" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "race" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/LoopDef" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "loop" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ForEachDef" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "for_each" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/RouterDef" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "router" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/TryCatchDef" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "try_catch" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/SubSequenceDef", "description": "Invoke another sequence as a sub-workflow." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "sub_sequence" ] } } } ], "description": "Invoke another sequence as a sub-workflow." }, { "allOf": [ { "$ref": "#/components/schemas/ABSplitDef", "description": "A/B split: route traffic to one of several variants by weight." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ab_split" ] } } } ], "description": "A/B split: route traffic to one of several variants by weight." }, { "allOf": [ { "$ref": "#/components/schemas/CancellationScopeDef", "description": "Cancellation scope: child blocks cannot be cancelled by external cancel signals.\nProvides subtree-level non-cancellability (Temporal-style structured concurrency)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "cancellation_scope" ] } } } ], "description": "Cancellation scope: child blocks cannot be cancelled by external cancel signals.\nProvides subtree-level non-cancellability (Temporal-style structured concurrency)." }, { "allOf": [ { "$ref": "#/components/schemas/SagaDef", "description": "Saga: sequential steps with compensating actions, rolled back in\nreverse order if any step's action fails." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "saga" ] } } } ], "description": "Saga: sequential steps with compensating actions, rolled back in\nreverse order if any step's action fails." } ], "description": "A block is either a leaf (step) or a composite (parallel, race, etc.).\n\nThis recursive enum IS the workflow DSL.\nEach variant wraps its definition in `Box` so the enum carries a pointer\nplus its variant tag. `StepDef` is large, with many `Option<...>` fields, and\nwithout boxing every `BlockDefinition` — even `SubSequence`, which is small\n— paid the full size. `Box` is transparent to both `serde` (the default\nimpl delegates to the inner type so wire format is unchanged) and `utoipa`\n(which forwards `ToSchema` through `Box`), so this is an internal\nrepresentation change only." }, "BlockId": { "type": "string" }, "BlockOutput": { "type": "object", "required": [ "id", "instance_id", "block_id", "output", "output_size", "attempt", "created_at" ], "properties": { "attempt": { "type": "integer", "format": "int32", "minimum": 0 }, "block_id": { "$ref": "#/components/schemas/BlockId" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "instance_id": { "$ref": "#/components/schemas/InstanceId" }, "output": {}, "output_ref": { "type": [ "string", "null" ], "description": "Reference key if output was externalized (exceeded size threshold)." }, "output_size": { "type": "integer", "format": "int32", "minimum": 0 } } }, "BlockOutputSummary": { "type": "object", "description": "Summary of one recorded output — the payload itself stays behind the\nlazy detail endpoint (`/instances/{id}/outputs`).", "required": [ "block_id", "attempt", "output_size", "status", "recorded_at" ], "properties": { "attempt": { "type": "integer", "format": "int32", "minimum": 0 }, "block_id": { "type": "string" }, "output_size": { "type": "integer", "format": "int32", "minimum": 0 }, "recorded_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "`ok` | `error` | `retry`." } } }, "BlockType": { "type": "string", "enum": [ "step", "parallel", "race", "loop", "for_each", "router", "try_catch", "sub_sequence", "ab_split", "cancellation_scope", "saga" ] }, "BreakerState": { "type": "string", "enum": [ "closed", "open", "half_open" ] }, "Budget": { "type": "object", "description": "Optional per-instance resource budget enforced by the scheduler.\n\nWhen any configured limit is exceeded (recorded LLM token usage or\nexecuted step count), the scheduler pauses the instance with\n`metadata.paused_reason = \"budget_exceeded\"` instead of letting it keep\nspending. Resume via the normal `Paused -> Scheduled` transition.\n\nv1 semantics: the budget is checked when the scheduler claims the\ninstance, *before* executing work for that tick. A resumed instance\ntherefore gets one more tick of work before the check fires again; if the\nbudget is still exceeded it pauses again on the next claim. A single\ntick's work may also overshoot the limit slightly (the check is\npre-flight, not mid-step).", "properties": { "max_attention_units": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum human-attention units reserved by the execution." }, "max_bytes_transferred": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum bytes transferred across runtime boundaries." }, "max_cost_microunits": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum monetary spend in millionths of the configured currency unit." }, "max_energy_millijoules": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum estimated energy consumption in millijoules." }, "max_external_calls": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum number of calls crossing an external-effect boundary." }, "max_input_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Max total LLM input (prompt) tokens recorded for this instance." }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Max total LLM output (completion) tokens recorded for this instance." }, "max_steps": { "type": [ "integer", "null" ], "format": "int64", "description": "Max executed steps (`context.runtime.total_steps_executed`)." }, "max_total_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Max combined (input + output) LLM tokens recorded for this instance." }, "max_wall_time_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum elapsed execution time in milliseconds." } } }, "BudgetAlert": { "type": "object", "description": "Durable record that a budget crossed a soft threshold. Exactly one row per\n`(budget_id, period_start, threshold_percent)`.", "required": [ "id", "event", "tenant_id", "budget_id", "period", "period_start", "threshold_percent", "spend_usd", "limit_usd", "blocking", "created_at" ], "properties": { "blocking": { "type": "boolean", "description": "Whether this threshold makes new dispatches fail (100% + hard cap)." }, "budget_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "event": { "type": "string", "description": "Always [`BUDGET_THRESHOLD_EVENT`]." }, "id": { "type": "string", "format": "uuid" }, "limit_usd": { "type": "number", "format": "double" }, "model": { "type": [ "string", "null" ] }, "period": { "$ref": "#/components/schemas/BudgetPeriod" }, "period_start": { "type": "string", "format": "date-time" }, "spend_usd": { "type": "number", "format": "double" }, "tenant_id": { "type": "string" }, "threshold_percent": { "type": "integer", "format": "int32", "minimum": 0 } } }, "BudgetPeriod": { "type": "string", "description": "Budget accounting period (UTC calendar boundaries).", "enum": [ "daily", "monthly" ] }, "BudgetRequest": { "type": "object", "description": "Create/replace body. `limit_usd` is the per-period estimated spend cap.", "required": [ "tenant_id", "period", "limit_usd" ], "properties": { "hard_cap": { "type": [ "boolean", "null" ], "description": "Fail new `llm_call` dispatches closed at 100%. Default `true`." }, "limit_usd": { "type": "number", "format": "double" }, "model": { "type": [ "string", "null" ], "description": "Model prefix filter (e.g. `gpt-5`, `claude-opus`); omit for all models." }, "period": { "$ref": "#/components/schemas/BudgetPeriod" }, "tenant_id": { "type": "string" }, "thresholds": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Soft alert thresholds in percent. Default `[50, 80, 100]`." } } }, "BudgetState": { "type": "string", "description": "Budget health derived from spend vs. limit.", "enum": [ "ok", "warning", "exceeded" ] }, "BudgetStatus": { "type": "object", "description": "Current-period status of one budget.", "required": [ "budget", "period_start", "period_end", "spend_usd", "percent_used", "state", "blocking", "unpriced_events" ], "properties": { "blocking": { "type": "boolean", "description": "True when a hard-capped budget is exhausted: new dispatches fail." }, "budget": { "$ref": "#/components/schemas/TenantBudget" }, "percent_used": { "type": "number", "format": "double" }, "period_end": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" }, "spend_usd": { "type": "number", "format": "double" }, "state": { "$ref": "#/components/schemas/BudgetState" }, "unpriced_events": { "type": "integer", "format": "int64", "description": "Usage from models without a known price is not counted." } } }, "BulkFilter": { "type": "object", "properties": { "metadata": { "type": [ "object", "null" ], "description": "Top-level `metadata` equality filters (key → value), combined with AND.\nServed by the same indexed path as `GET /instances?metadata.k=v`.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "namespace": { "type": [ "string", "null" ] }, "sequence_id": { "type": [ "string", "null" ], "format": "uuid" }, "states": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/InstanceState" } }, "tenant_id": { "type": [ "string", "null" ] } } }, "BulkRescheduleRequest": { "type": "object", "required": [ "filter", "offset_secs" ], "properties": { "filter": { "$ref": "#/components/schemas/BulkFilter" }, "offset_secs": { "type": "integer", "format": "int64", "description": "Shift `next_fire_at` by this many seconds (positive = later, negative = earlier)." } } }, "BulkUpdateStateRequest": { "type": "object", "required": [ "filter", "state" ], "properties": { "filter": { "$ref": "#/components/schemas/BulkFilter" }, "state": { "$ref": "#/components/schemas/InstanceState" } } }, "CanaryRequest": { "type": "object", "required": [ "percent" ], "properties": { "percent": { "type": "integer", "format": "int32", "description": "Percentage of new instances routed to the candidate (1–100).", "minimum": 0 } } }, "CancellationScopeDef": { "type": "object", "description": "Cancellation scope: wraps child blocks in a non-cancellable boundary.\n\nWhen a cancel signal is received, blocks inside a `CancellationScope`\ncontinue executing until completion. The cancel takes effect only after\nall scoped blocks finish.", "required": [ "id", "blocks" ], "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockDefinition" }, "description": "Child blocks protected from cancellation." }, "id": { "$ref": "#/components/schemas/BlockId" } } }, "CapsuleRequirements": { "type": "object", "description": "Requirements that must be satisfied before accepting a capsule.", "properties": { "classification": { "oneOf": [ { "$ref": "#/components/schemas/DataClassification", "description": "Data classification the `policy` is evaluated for (default `internal`)." }, { "type": "null" } ] }, "credentials": { "type": "array", "items": { "type": "string" } }, "handlers": { "type": "array", "items": { "type": "string" } }, "hardware": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "object", "description": "Placement: every label must be advertised with exactly this value.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "minimum_trust": { "oneOf": [ { "$ref": "#/components/schemas/RuntimeTrustLevel" }, { "type": "null" } ] }, "plugins": { "type": "array", "items": { "type": "string" } }, "policy": { "oneOf": [ { "$ref": "#/components/schemas/LocalityPolicy", "description": "Locality/residency policy evaluated at dispatch (recorded as a\nplacement decision) and re-evaluated against every claimant." }, { "type": "null" } ] }, "prefer": { "oneOf": [ { "$ref": "#/components/schemas/PlacementPreference", "description": "Soft preference (sticky affinity / preferred labels) with a bounded\nwait. Never widens eligibility; see\n[`crate::placement::PlacementPreference`]." }, { "type": "null" } ] }, "regions": { "type": "array", "items": { "type": "string" } }, "requires_human_ui": { "type": "boolean" }, "requires_network": { "type": "boolean" }, "residency": { "type": [ "string", "null" ], "description": "Placement: data-residency zone; only runtimes advertising the label\n`residency=` may claim. Never relaxed." }, "runtime_id": { "oneOf": [ { "$ref": "#/components/schemas/RuntimeId", "description": "Placement: only this runtime may claim. The task then acts as that\nnode's durable mailbox: it stays `pending` until the node polls." }, { "type": "null" } ] }, "runtime_kinds": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeKind" }, "description": "Placement: only runtimes of these kinds may claim. Empty = any kind.\nA list that excludes `server` forces remote dispatch even when the\nserver has the handler registered in-process." } } }, "CertificationRequest": { "type": "object", "required": [ "subject", "results", "issued_at", "expires_at" ], "properties": { "expires_at": { "type": "string", "format": "date-time" }, "issued_at": { "type": "string", "format": "date-time" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ConformanceCheckResult" } }, "subject": { "type": "string" } } }, "ChangeCursor": { "type": "object", "description": "Exclusive position in the tenant audit feed. Ordering is total even when\nmultiple changes share a timestamp because UUID is the tie-breaker.", "required": [ "created_at", "id" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" } } }, "ChangePage": { "type": "object", "required": [ "changes", "has_more" ], "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "Checkpoint": { "type": "object", "description": "A checkpoint captures execution state at a point in time for efficient recovery.", "required": [ "id", "instance_id", "checkpoint_data", "created_at" ], "properties": { "checkpoint_data": { "description": "Snapshot of execution state: completed block IDs, context, etc." }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "instance_id": { "$ref": "#/components/schemas/InstanceId" } } }, "CircuitBreakerState": { "type": "object", "description": "Circuit breaker state for a (tenant, handler) pair.\n\nBreakers are scoped per-tenant so a noisy customer cannot trip the circuit\nfor an unrelated tenant sharing the same handler name.", "required": [ "tenant_id", "handler", "state", "failure_count", "failure_threshold", "cooldown_secs" ], "properties": { "cooldown_secs": { "type": "integer", "format": "int64", "description": "Cooldown period in seconds before transitioning from Open to `HalfOpen`.", "minimum": 0 }, "failure_count": { "type": "integer", "format": "int32", "description": "Consecutive failure count.", "minimum": 0 }, "failure_threshold": { "type": "integer", "format": "int32", "description": "Threshold of failures before opening the circuit.", "minimum": 0 }, "handler": { "type": "string", "description": "Handler name this breaker protects." }, "opened_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the circuit was last opened (to compute cooldown expiry)." }, "state": { "$ref": "#/components/schemas/BreakerState" }, "tenant_id": { "$ref": "#/components/schemas/TenantId", "description": "Owning tenant — breakers are isolated per-tenant." } } }, "ClaimedWorkerTask": { "allOf": [ { "$ref": "#/components/schemas/WorkerTask" }, { "type": "object", "properties": { "runtime_kinds": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeKind" }, "description": "`$runtime.runtime_kinds`: kinds allowed to claim (empty = any)." }, "target_runtime_id": { "oneOf": [ { "$ref": "#/components/schemas/RuntimeId", "description": "`$runtime.runtime_id`: the only node allowed to claim (mailbox)." }, { "type": "null" } ] } } } ], "description": "A claimed task as delivered to a runtime node: the task (with its\n`effect_id`, `continuity_epoch`, and effective `lease_secs`) plus its\nplacement echoed at the top level for debugging." }, "ClusterNode": { "type": "object", "description": "Represents a running engine node in a multi-node cluster.", "required": [ "id", "name", "status", "registered_at", "last_heartbeat_at", "drain" ], "properties": { "capabilities_withdrawn": { "type": "boolean", "description": "New placement/claim capability was withdrawn before shutdown." }, "drain": { "type": "boolean", "description": "If true, the node should stop accepting new work and drain." }, "drain_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "First durable transition into draining." }, "execution_handoff_evidence": { "type": [ "string", "null" ], "description": "Durable evidence written only after the local scheduler has drained." }, "id": { "type": "string", "format": "uuid", "description": "Unique node ID (generated at startup)." }, "last_heartbeat_at": { "type": "string", "format": "date-time", "description": "Last heartbeat timestamp." }, "name": { "type": "string", "description": "Human-readable node name (e.g. hostname or pod name)." }, "registered_at": { "type": "string", "format": "date-time", "description": "When this node first registered." }, "status": { "$ref": "#/components/schemas/NodeStatus", "description": "Node status." }, "stopped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Graceful or stale stop time." } } }, "CommercialContinuityPlan": { "type": "object", "description": "Enforceable plan for hosted relay, Conformance Cloud, and OEM deployments.", "required": [ "deployment", "tenant_isolation", "signed_receipts", "conformance_required", "evidence_retention_days", "allowed_protocol_majors" ], "properties": { "allowed_protocol_majors": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "conformance_required": { "type": "boolean" }, "deployment": { "$ref": "#/components/schemas/RelayDeployment" }, "evidence_retention_days": { "type": "integer", "format": "int32", "minimum": 0 }, "oem_product_id": { "type": [ "string", "null" ] }, "signed_receipts": { "type": "boolean" }, "tenant_isolation": { "type": "boolean" }, "usage_meter": { "type": [ "string", "null" ] } } }, "CompensationVerificationPolicy": { "type": "string", "enum": [ "handler_result", "provider_receipt", "manual" ] }, "CompilePolicyRequest": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string" } } }, "CompiledPlacementPolicy": { "type": "object", "description": "Human-editable placement policy compiled into the durable core vocabulary.", "required": [ "source", "requirements", "policy", "classification", "source_sha256" ], "properties": { "classification": { "$ref": "#/components/schemas/DataClassification" }, "policy": { "$ref": "#/components/schemas/LocalityPolicy" }, "requirements": { "$ref": "#/components/schemas/CapsuleRequirements" }, "source": { "type": "string" }, "source_sha256": { "type": "string" } } }, "CompleteRequest": { "type": "object", "required": [ "worker_id", "claim_epoch", "output" ], "properties": { "claim_epoch": { "type": "integer", "format": "int64", "minimum": 0 }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/StepLogEntry" }, "description": "Optional log lines the worker captured while running this task." }, "output": {}, "traceparent": { "type": [ "string", "null" ], "description": "W3C `traceparent` of the worker's span (alternatively sent as the\n`traceparent` HTTP header) so the completion joins the dispatch trace." }, "worker_id": { "type": "string" } } }, "Confidence": { "type": "string", "description": "How confident the producer of a finding is in its diagnosis.\n\nDiagnosis surfaces must never claim certainty while multiple\nexplanations remain possible — pick the honest level.", "enum": [ "low", "medium", "high", "certain" ] }, "ConformanceCertificate": { "type": "object", "required": [ "protocol", "subject", "score", "results_sha256", "issued_at", "expires_at", "issuer" ], "properties": { "expires_at": { "type": "string", "format": "date-time" }, "issued_at": { "type": "string", "format": "date-time" }, "issuer": { "type": "string" }, "protocol": { "$ref": "#/components/schemas/ProtocolVersion" }, "results_sha256": { "type": "string" }, "score": { "$ref": "#/components/schemas/ContinuityScore" }, "signature": { "type": [ "string", "null" ] }, "subject": { "type": "string" } } }, "ConformanceCheck": { "type": "string", "enum": [ "protocol_compatibility", "atomic_ownership", "stale_owner_rejected", "duplicate_effect_fenced", "offline_resume", "policy_enforced", "receipt_verifiable", "tenant_isolation" ] }, "ConformanceCheckResult": { "type": "object", "required": [ "check", "passed", "evidence_sha256", "duration_ms" ], "properties": { "check": { "$ref": "#/components/schemas/ConformanceCheck" }, "duration_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "evidence_sha256": { "type": "string" }, "finding": { "type": [ "string", "null" ] }, "passed": { "type": "boolean" } } }, "ContextAccess": { "type": "object", "description": "Controls which context sections a step handler can see.\nWhen set, only the listed sections are passed to the handler.\n\n`data` supports field-level granularity via [`FieldAccess`]; other sections\nare all-or-nothing because they are small by design (`config`, `runtime`)\nor append-only streams (`audit`).", "properties": { "audit": { "type": "boolean", "description": "Allow reading `context.audit`." }, "config": { "type": "boolean", "description": "Allow reading `context.config`." }, "data": { "description": "Controls read access to `context.data`. Accepts legacy `true`/`false`,\nthe keywords `\"all\"`/`\"none\"`, or an explicit `{\"fields\": [..]}` list." }, "runtime": { "type": "boolean", "description": "Allow reading `context.runtime`." } } }, "ContinuityId": { "type": "string", "format": "uuid" }, "ContinuityScore": { "type": "object", "required": [ "score_millipoints", "passed", "total", "mandatory_failures" ], "properties": { "mandatory_failures": { "type": "array", "items": { "$ref": "#/components/schemas/ConformanceCheck" } }, "passed": { "type": "integer", "minimum": 0 }, "score_millipoints": { "type": "integer", "format": "int32", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "CountResponse": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "format": "int64", "minimum": 0 } } }, "CreateBrowserSessionRequest": { "type": "object", "required": [ "handlers" ], "properties": { "handlers": { "type": "array", "items": { "type": "string" }, "description": "Handler allowlist: polls for any other handler are refused." }, "queues": { "type": "array", "items": { "type": "string" }, "description": "Named queues the tab may poll with `/workers/tasks/poll/queue`." }, "runtime_id": { "type": [ "string", "null" ], "description": "Runtime identity to bind (a fresh one is minted when absent)." }, "ttl_secs": { "type": [ "integer", "null" ], "format": "int32", "description": "Token lifetime in seconds (default 900, max 3600).", "minimum": 0 } } }, "CreateBrowserSessionResponse": { "type": "object", "required": [ "token", "runtime_id", "expires_at", "handlers" ], "properties": { "expires_at": { "type": "string", "format": "date-time" }, "handlers": { "type": "array", "items": { "type": "string" } }, "queues": { "type": "array", "items": { "type": "string" } }, "runtime_id": { "type": "string" }, "token": { "type": "string" } } }, "CreateCredentialRequest": { "type": "object", "required": [ "id", "name", "value" ], "properties": { "description": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/CredentialKind" }, "name": { "type": "string" }, "refresh_token": { "type": [ "string", "null" ] }, "refresh_url": { "type": [ "string", "null" ] }, "tenant_id": { "type": "string" }, "value": { "type": "string", "description": "Raw secret value (typically JSON) — will be stored and redacted on read." } } }, "CreateCronRequest": { "type": "object", "required": [ "tenant_id", "namespace", "sequence_id", "cron_expr" ], "properties": { "cron_expr": { "type": "string" }, "enabled": { "type": "boolean" }, "metadata": {}, "namespace": { "$ref": "#/components/schemas/Namespace" }, "overlap_policy": { "$ref": "#/components/schemas/OverlapPolicy", "description": "Behavior when a fire is due while a previous run is still active:\n`allow` (default), `skip`, `buffer_one`, `cancel_previous`." }, "sequence_id": { "$ref": "#/components/schemas/SequenceId" }, "tenant_id": { "$ref": "#/components/schemas/TenantId" }, "timezone": { "type": "string" } } }, "CreateDeviceSessionRequest": { "type": "object", "required": [ "device_id", "runtime_id" ], "properties": { "device_id": { "type": "string", "description": "The mobile device (`MobileEngineConfig.device_id`) the token acts for." }, "handlers": { "type": "array", "items": { "type": "string" }, "description": "Handlers the phone may poll and advertise. Empty = the phone only\ndelegates (it never claims tasks)." }, "runtime_id": { "type": "string", "description": "The phone's persisted runtime id (`MobileEngine.node_runtime_id()`):\nits `worker_id` for leases and the owner of executions it hosts." }, "ttl_secs": { "type": [ "integer", "null" ], "format": "int32", "description": "Token lifetime in seconds (default 3600, max 86400).", "minimum": 0 } } }, "CreateDeviceSessionResponse": { "type": "object", "required": [ "token", "device_id", "runtime_id", "expires_at", "handlers" ], "properties": { "device_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "handlers": { "type": "array", "items": { "type": "string" } }, "runtime_id": { "type": "string" }, "token": { "type": "string" } } }, "CreateInstanceRequest": { "type": "object", "required": [ "sequence_id", "tenant_id", "namespace" ], "properties": { "budget": { "oneOf": [ { "$ref": "#/components/schemas/Budget", "description": "Optional resource budget (token/step caps) enforced by the scheduler.\nWhen any configured limit is exceeded the instance is paused with\n`metadata.paused_reason = \"budget_exceeded\"`. Default: no budget." }, { "type": "null" } ] }, "concurrency_key": { "type": [ "string", "null" ] }, "context": { "$ref": "#/components/schemas/ExecutionContext" }, "dry_run": { "type": "boolean", "description": "Run this instance in dry-run mode: side-effecting steps (HTTP/LLM/MCP\ncalls, agent loops, event/signal emission, memory writes, block\ninjection, external plugins) skip their real effect and return a stub;\ncontrol flow and templating run normally. Any sequence can be run dry.\nDefault false." }, "dry_run_auto_approve": { "type": "boolean", "description": "When dry-run is on, auto-approve `human_review` gates with the default\nchoice so the simulation flows past them instead of pausing. Ignored\nunless `dry_run` is true. Default false." }, "idempotency_key": { "type": [ "string", "null" ] }, "max_concurrency": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "metadata": {}, "namespace": { "$ref": "#/components/schemas/Namespace" }, "next_fire_at": { "type": [ "string", "null" ], "format": "date-time" }, "priority": { "oneOf": [ { "$ref": "#/components/schemas/Priority", "description": "Explicit priority. When omitted, the lane decides: `priority_lane`,\nthen the sequence's `placement.priority_lane`, then the tenant plan's\n`default_priority_lane`, else `normal`." }, { "type": "null" } ] }, "priority_lane": { "oneOf": [ { "$ref": "#/components/schemas/PriorityLane", "description": "Priority lane (`premium` → high, `standard` → normal, `batch` → low).\nIgnored when `priority` is set." }, { "type": "null" } ] }, "sequence_id": { "$ref": "#/components/schemas/SequenceId" }, "sub_tenant": { "type": [ "string", "null" ], "description": "End customer inside the tenant. The `X-Orch8-Sub-Tenant` header is\nauthoritative; a body value must match it." }, "tenant_id": { "$ref": "#/components/schemas/TenantId" }, "timezone": { "type": "string" } } }, "CreatePoolRequest": { "type": "object", "required": [ "tenant_id", "name" ], "properties": { "name": { "type": "string" }, "strategy": { "$ref": "#/components/schemas/RotationStrategy" }, "tenant_id": { "type": "string" } } }, "CreateReleaseRequest": { "type": "object", "required": [ "tenant_id", "baseline_sequence_id", "candidate_sequence_id" ], "properties": { "baseline_sequence_id": { "type": "string", "format": "uuid" }, "candidate_sequence_id": { "type": "string", "format": "uuid" }, "gates": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseGate" } }, "in_flight_policy": { "$ref": "#/components/schemas/InFlightPolicy" }, "target": { "oneOf": [ { "$ref": "#/components/schemas/ReleaseTarget", "description": "Optional sub-tenant staged rollout: sub-tenant scoped instances are\nrouted by sub-tenant instead of per-instance cohorts; unscoped\ninstances stay on the baseline until promotion. Unknown fields in\nthe target are rejected (the persisted type itself is lenient)." }, { "type": "null" } ] }, "tenant_id": { "type": "string" } } }, "CreateRoutingRuleRequest": { "type": "object", "required": [ "tenant_id", "handler_name", "queue_override" ], "properties": { "enabled": { "type": "boolean" }, "handler_name": { "type": "string" }, "match_queue": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "format": "int32" }, "queue_override": { "type": "string" }, "tenant_id": { "type": "string" } } }, "CreateSessionRequest": { "type": "object", "required": [ "tenant_id", "session_key" ], "properties": { "data": {}, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "session_key": { "type": "string" }, "tenant_id": { "$ref": "#/components/schemas/TenantId" } } }, "CreateShareRequest": { "type": "object", "properties": { "allowed_fields": { "type": "array", "items": { "type": "string" }, "description": "Top-level `context.data` keys to expose publicly. Default: none." }, "expires_in_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Lifetime in seconds (60..=7776000). Default 7 days." } } }, "CreateShareResponse": { "type": "object", "required": [ "id", "token", "url", "embed_url", "embed_snippet", "expires_at", "allowed_fields" ], "properties": { "allowed_fields": { "type": "array", "items": { "type": "string" } }, "embed_snippet": { "type": "string", "description": "Paste-in `