{ "openapi": "3.1.0", "info": { "title": "Carryframe legacy API-key endpoint", "version": "0.2.0-staging", "description": "Legacy API-key contract ONLY for persistent-orchestration-api-stagin.vercel.app. This does not specify authentication to carryframe.com, which requires enrolled operator identity; see /docs.html. Staging only. Model contributions and proposed records require separate review." }, "servers": [ { "url": "https://persistent-orchestration-api-stagin.vercel.app/api/orchestration", "description": "Isolated staging API; scoped staging credentials only" } ], "x-service-status": "staging-api-live", "x-versioning-policy": { "uri_major": true, "beta_freeze": "first_external_beta_credential", "incompatible_changes": "new_major_path", "retirement_notice": "explicit_approval_required" }, "x-max-request-body-bytes": 65536, "security": [{ "ApiKeyBearer": [] }], "tags": [ { "name": "Account" }, { "name": "Orchestrations" }, { "name": "Executions" }, { "name": "Records" }, { "name": "Successions" }, { "name": "Roles" }, { "name": "Lifecycle" }, { "name": "Usage" } ], "paths": { "/v1/account/billing": { "get": {"tags":["Account"],"summary":"Own platform plan, subscription and journal metering", "description":"Dedicated billing configuration and matching database mode required; otherwise 503. Returns plan, status, paid_until, mode (test or live), usage (journal_events, retained_payload_bytes as decimal strings; month_start), checkout_available and portal_available. Test mode is the default. Live mode requires separate explicit activation; the current staging service remains test-only. Usage windows are UTC calendar months, not invoice periods.", "security":[{"CustomerBearer":[]}],"responses":{"200":{"description":"Own billing and usage state"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}} }, "/v1/account/billing/checkout": { "post": {"tags":["Account"],"summary":"Create or reconcile one platform test Checkout Session", "description":"Body exactly {}. No caller-selected price, tenant or redirect. Returns {url}. Nonterminal subscribers use the portal. A provider-confirmed canceled or incomplete_expired subscription can restart with its old binding retained. A provider-confirmed expired Checkout session can be replaced; a completed session awaiting its webhook returns 409 checkout_payment_reconciling. An uncertain creation attempt older than 23 hours requires operator reconciliation, never blind recreation.", "security":[{"CustomerBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}}, "responses":{"200":{"description":"Stripe test checkout URL"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}} }, "/v1/account/billing/portal": { "post": {"tags":["Account"],"summary":"Open platform-only test subscription portal; returns {url}", "security":[{"CustomerBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}}, "responses":{"200":{"description":"Stripe portal URL"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}} }, "/v1/billing/webhook": { "post": {"tags":["Account"],"summary":"Stripe test webhook; verified raw payload only","security":[], "parameters":[{"in":"header","name":"Stripe-Signature","required":true,"schema":{"type":"string"}}], "requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}, "responses":{"200":{"description":"Verified event processed or unrelated product ignored"},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}} }, "/v1/account/config": { "get": { "tags": ["Account"], "summary": "Read public signup identity configuration", "security": [], "responses": { "200": { "description": "Supabase Auth URL and public publishable key for independent customer signup." }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/account": { "post": { "tags": ["Account"], "summary": "Create one organization for a confirmed Supabase Auth user", "security": [{ "CustomerBearer": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["organization_name"], "properties": { "organization_name": { "type": "string", "minLength": 1, "maxLength": 100 } } } } } }, "responses": { "201": { "description": "Organization created with conservative staging quotas." }, "200": { "description": "Existing organization, same name." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "get": { "tags": ["Account"], "summary": "Read the authenticated customer's organization", "security": [{ "CustomerBearer": [] }], "responses": { "200": { "description": "Organization ID and name." }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/account/usage": { "get": { "tags": ["Account"], "summary": "Read this customer's organization usage and limits", "security": [{ "CustomerBearer": [] }], "responses": { "200": { "description": "Own-tenant usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/account/keys": { "get": { "tags": ["Account"], "summary": "List own API-key metadata without secrets", "security": [{ "CustomerBearer": [] }], "responses": { "200": { "description": "Own key metadata." }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": ["Account"], "summary": "Issue one API key; secret returned once", "security": [{ "CustomerBearer": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["label", "scopes"], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "One-time raw key and metadata; never cache this response." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/account/keys/{keyId}": { "delete": { "tags": ["Account"], "summary": "Revoke an owned API key immediately", "security": [{ "CustomerBearer": [] }], "parameters": [{ "name": "keyId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }], "responses": { "200": { "description": "Key revoked; replay is harmless." }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/account/keys/{keyId}/rotate": { "post": { "tags": ["Account"], "summary": "Atomically issue a replacement and revoke the old key", "security": [{ "CustomerBearer": [] }], "parameters": [{ "name": "keyId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "201": { "description": "One-time replacement key and metadata." }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/v1/usage": { "get": { "tags": ["Usage"], "summary": "Read current application limits and UTC-day usage", "description": "Accounted tokens include conservative reservations for dispatched work whose actual usage is not yet known. Uncertain delivery remains held until the private operator reconciliation boundary records attributable usage or no-charge evidence.", "x-required-scope": "orchestrations:read", "responses": { "200": { "description": "Tenant-scoped limits and usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations": { "get": { "tags": ["Orchestrations"], "summary": "Resolve an orchestration by an exact application-owned reference", "description": "References are unique only within the authenticated application. This safe read supports reconciliation after an uncertain create response.", "x-required-scope": "orchestrations:read", "parameters": [{ "name": "client_reference", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/ClientReference" } }], "responses": { "200": { "$ref": "#/components/responses/Orchestration" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": ["Orchestrations"], "summary": "Create a durable orchestration", "x-required-scope": "orchestrations:write", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrchestration" } } } }, "responses": { "201": { "$ref": "#/components/responses/Orchestration" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}": { "get": { "tags": ["Orchestrations"], "summary": "Read an orchestration", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }], "responses": { "200": { "$ref": "#/components/responses/Orchestration" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/export": { "get": { "tags": ["Orchestrations"], "summary": "Export one orchestration with a canonical digest", "description": "Returns a repeatable-read, tenant-scoped snapshot without API secrets or operational lease tokens. The digest covers the format, version, identity, through revision and data object.", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }], "responses": { "200": { "description": "Digest-verifiable orchestration export." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/exports": { "post": { "tags": ["Orchestrations"], "summary": "Create a resumable orchestration export", "description": "Materializes one repeatable-read snapshot as independently digest-verifiable chunks. The seven-day derived view never replaces raw lineage and can be resumed without repeating the snapshot transaction.", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "201": { "description": "Snapshot manifest with ordered chunk digests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumableExportManifest" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/exports/{exportId}/chunks/{chunkIndex}": { "get": { "tags": ["Orchestrations"], "summary": "Read one resumable export chunk", "description": "Returns one bounded base64 chunk. Verify its digest before appending it to the ordered export stream, then verify the manifest digest over the complete byte stream.", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/ExportId" }, { "$ref": "#/components/parameters/ChunkIndex" }], "responses": { "200": { "description": "One immutable export chunk.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumableExportChunk" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/events": { "get": { "tags": ["Orchestrations"], "summary": "Read an ordered journal page", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Exclusive revision cursor. Defaults to 0." }], "responses": { "200": { "description": "At most 100 events and a continuation cursor.", "content": { "application/json": { "schema": { "type": "object", "required": ["orchestration_id", "through_revision", "events", "next_after"], "additionalProperties": false, "properties": { "orchestration_id": { "$ref": "#/components/schemas/Uuid" }, "through_revision": { "$ref": "#/components/schemas/Revision" }, "events": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Event" } }, "next_after": { "anyOf": [{ "$ref": "#/components/schemas/Revision" }, { "type": "null" }] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/inputs": { "post": { "tags": ["Orchestrations"], "summary": "Append caller-owned input", "x-required-scope": "orchestrations:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendInput" } } } }, "responses": { "201": { "description": "Input durably appended." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/executions": { "post": { "tags": ["Executions"], "summary": "Queue a bounded model contribution", "x-required-scope": "executions:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueExecution" } } } }, "responses": { "202": { "description": "Execution queued and pinned to the supplied revision." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/executions/{executionId}": { "get": { "tags": ["Executions"], "summary": "Inspect an execution", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/ExecutionId" }], "responses": { "200": { "description": "Execution state and provider provenance." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/executions/{executionId}/context": { "get": { "tags": ["Executions"], "summary": "Inspect the immutable execution input segment", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/ExecutionId" }], "responses": { "200": { "description": "Frozen context, digest and token bounds." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/records": { "post": { "tags": ["Records"], "summary": "Propose a record", "x-required-scope": "records:write", "description": "A proposal is not accepted state and receives no authority merely because it was generated by a model.", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeRecord" } } } }, "responses": { "201": { "description": "Immutable version 1 proposed." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/records/{recordId}/versions": { "post": { "tags": ["Records"], "summary": "Propose the next immutable record version", "x-required-scope": "records:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RecordId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeRecordVersion" } } } }, "responses": { "201": { "description": "Next immutable version proposed." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/records/{recordId}/reviews": { "post": { "tags": ["Records"], "summary": "Accept, reject or withdraw a record version", "x-required-scope": "records:review", "description": "Acceptance records an application decision for a stated purpose. It is not proof of independent competence or universal truth.", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RecordId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRecord" } } } }, "responses": { "201": { "description": "Review durably recorded." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/records/{recordId}/versions/{version}": { "get": { "tags": ["Records"], "summary": "Read one immutable record version", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RecordId" }, { "name": "version", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/RecordVersion" } }], "responses": { "200": { "description": "Content, digest, proposer, reviews and evidence lineage." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/successions": { "post": { "tags": ["Successions"], "summary": "Start a bounded predecessor-successor demonstration", "description": "Queues a successor against a successful predecessor. The application owns the demonstration and requested authority envelope; neither is platform authority until independently qualified.", "x-required-scope": "successions:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSuccession" } } } }, "responses": { "202": { "description": "Succession demonstration and successor execution durably queued." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/successions/{successionId}": { "get": { "tags": ["Successions"], "summary": "Inspect one succession and its exact authority disposition", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/SuccessionId" }], "responses": { "200": { "description": "Tenant-scoped succession state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Succession" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/successions/{successionId}/reviews": { "post": { "tags": ["Successions"], "summary": "Independently qualify or reject a successor demonstration", "description": "The reviewing API key must differ from the proposing key. Qualification grants only the exact caller-owned authority envelope requested when the demonstration started.", "x-required-scope": "successions:review", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/SuccessionId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewSuccession" } } } }, "responses": { "201": { "description": "Independent qualification decision durably recorded." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/roles": { "get": { "tags": ["Roles"], "summary": "List persistent roles", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }], "responses": { "200": { "description": "All durable roles in the orchestration." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/roles/{roleId}": { "get": { "tags": ["Roles"], "summary": "Read one persistent role", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RoleId" }], "responses": { "200": { "description": "Current role state and version." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/role-proposals": { "post": { "tags": ["Roles"], "summary": "Propose a root-orchestrator role lifecycle change", "description": "Automatic policy applies a valid proposal atomically. Client-approval policy leaves it pending.", "x-required-scope": "roles:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleLifecycleProposal" } } } }, "responses": { "201": { "description": "Proposal applied automatically." }, "202": { "description": "Proposal awaits client approval." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/role-proposals/{proposalId}": { "get": { "tags": ["Roles"], "summary": "Read a role lifecycle proposal", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/ProposalId" }], "responses": { "200": { "description": "Lifecycle proposal state." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/role-proposals/{proposalId}/reviews": { "post": { "tags": ["Roles"], "summary": "Approve or reject a pending role lifecycle proposal", "x-required-scope": "roles:review", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/ProposalId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRoleLifecycle" } } } }, "responses": { "201": { "description": "Review and any resulting lifecycle change recorded atomically." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/roles/{roleId}/obligations": { "get": { "tags": ["Roles"], "summary": "Read obligations currently held by a role", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RoleId" }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0 } }], "responses": { "200": { "description": "At most 100 current obligations and a continuation cursor." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": ["Roles"], "summary": "Create a role-held obligation", "x-required-scope": "roles:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RoleId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleObligation" } } } }, "responses": { "201": { "description": "Obligation created." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/roles/{roleId}/obligations/{obligationId}/transfer": { "post": { "tags": ["Roles"], "summary": "Transfer an open obligation to an active role", "x-required-scope": "roles:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RoleId" }, { "$ref": "#/components/parameters/ObligationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRoleObligation" } } } }, "responses": { "201": { "description": "Transfer recorded." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/roles/{roleId}/obligations/{obligationId}/resolve": { "post": { "tags": ["Roles"], "summary": "Resolve an obligation held by a role", "x-required-scope": "roles:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RoleId" }, { "$ref": "#/components/parameters/ObligationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRoleObligation" } } } }, "responses": { "201": { "description": "Resolution recorded." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/roles/{roleId}/messages": { "post": { "tags": ["Roles"], "summary": "Send a durable role-to-role message", "x-required-scope": "messages:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RoleId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRoleMessage" } } } }, "responses": { "201": { "description": "Message appended to the recipient inbox." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/roles/{roleId}/inbox": { "get": { "tags": ["Roles"], "summary": "Read a durable role inbox", "x-required-scope": "orchestrations:read", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RoleId" }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0 } }], "responses": { "200": { "description": "At most 100 messages and a continuation cursor." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/roles/{roleId}/records": { "post": { "tags": ["Records", "Roles"], "summary": "Propose a role-scoped record", "x-required-scope": "records:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/RoleId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeRecord" } } } }, "responses": { "201": { "description": "Immutable role-scoped record version proposed." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/pause": { "$ref": "#/components/pathItems/Pause" }, "/v1/orchestrations/{orchestrationId}/resume": { "$ref": "#/components/pathItems/Resume" }, "/v1/orchestrations/{orchestrationId}/cancel": { "$ref": "#/components/pathItems/Cancel" } }, "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "por_v1.." }, "CustomerBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Supabase Auth access JWT" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" } }, "OrchestrationId": { "name": "orchestrationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "ExecutionId": { "name": "executionId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "RoleId": { "name": "roleId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "ProposalId": { "name": "proposalId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "ObligationId": { "name": "obligationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "SuccessionId": { "name": "successionId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "RecordId": { "name": "recordId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "ExportId": { "name": "exportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "ChunkIndex": { "name": "chunkIndex", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } }, "pathItems": { "Pause": { "post": { "tags": ["Lifecycle"], "summary": "Pause future dispatch", "x-required-scope": "orchestrations:write", "description": "A preparing execution is requeued and its lease is fenced. A dispatched request is not undone.", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "$ref": "#/components/requestBodies/Lifecycle" }, "responses": { "200": { "description": "Paused." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "Resume": { "post": { "tags": ["Lifecycle"], "summary": "Resume future dispatch", "x-required-scope": "orchestrations:write", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "$ref": "#/components/requestBodies/Lifecycle" }, "responses": { "200": { "description": "Active." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "Cancel": { "post": { "tags": ["Lifecycle"], "summary": "Terminally cancel future work", "x-required-scope": "orchestrations:write", "description": "Queued or preparing work is cancelled. Dispatched or uncertain work is returned as unresolved and remains inspectable.", "parameters": [{ "$ref": "#/components/parameters/OrchestrationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "$ref": "#/components/requestBodies/Lifecycle" }, "responses": { "200": { "description": "Cancelled; response identifies any unresolved execution." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } } }, "requestBodies": { "Lifecycle": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleTransition" } } } } }, "responses": { "Orchestration": { "description": "Durable orchestration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Orchestration" } } } }, "Error": { "description": "Sanitized API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Uuid": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "Revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740990 }, "RecordVersion": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "ClientReference": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._:-]+$" }, "EvidenceRevisions": { "type": "array", "maxItems": 32, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Revision" } }, "CreateOrchestration": { "type": "object", "additionalProperties": false, "properties": { "client_reference": { "$ref": "#/components/schemas/ClientReference" }, "initial_state": {}, "instructions": { "type": "string", "x-max-utf8-bytes": 8192 }, "metadata": {}, "role_policy": { "$ref": "#/components/schemas/RolePolicy" } } }, "AppendInput": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "input"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "input": {} } }, "QueueExecution": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "model"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "role_id": { "$ref": "#/components/schemas/Uuid" }, "model": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "accepted_record_ids": { "type": "array", "maxItems": 256, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Uuid" }, "description": "When present, include exactly these accepted records in the execution context. Omission preserves the all-visible default." } } }, "RolePolicy": { "type": "object", "additionalProperties": false, "required": ["lifecycle_mode"], "properties": { "lifecycle_mode": { "type": "string", "enum": ["automatic", "client_approval"] } } }, "RoleLifecycleProposal": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "operation", "change", "reason"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "operation": { "type": "string", "enum": ["create", "amend", "suspend", "resume", "split", "merge", "close"] }, "change": { "type": "object", "x-max-canonical-json-bytes": 16384 }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "ReviewRoleLifecycle": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "verdict", "reason"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "verdict": { "type": "string", "enum": ["approved", "rejected"] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "CreateRoleObligation": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "kind", "content"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "kind": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9._:-]{0,63}$" }, "content": { "type": "object", "x-max-canonical-json-bytes": 16384 } } }, "TransferRoleObligation": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "to_role_id", "reason"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "to_role_id": { "$ref": "#/components/schemas/Uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "ResolveRoleObligation": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "resolution"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "resolution": { "type": "object", "x-max-canonical-json-bytes": 16384 } } }, "SendRoleMessage": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "to_role_id", "kind", "content"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "to_role_id": { "$ref": "#/components/schemas/Uuid" }, "kind": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9._:-]{0,63}$" }, "content": { "type": "object", "x-max-canonical-json-bytes": 16384 } } }, "ProposeRecord": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "kind", "content"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "kind": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9._:-]{0,63}$" }, "content": { "x-max-canonical-json-bytes": 32768 }, "evidence_revisions": { "$ref": "#/components/schemas/EvidenceRevisions" } } }, "ProposeRecordVersion": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "expected_version", "content"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "expected_version": { "$ref": "#/components/schemas/RecordVersion" }, "content": { "x-max-canonical-json-bytes": 32768 }, "evidence_revisions": { "$ref": "#/components/schemas/EvidenceRevisions" } } }, "ReviewRecord": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "version", "verdict", "reason", "purpose", "evidence_revisions"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "version": { "$ref": "#/components/schemas/RecordVersion" }, "verdict": { "type": "string", "enum": ["accepted", "rejected", "withdrawn"] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 1000 }, "evidence_revisions": { "$ref": "#/components/schemas/EvidenceRevisions", "description": "At least one item is required when verdict is accepted." } } }, "StartSuccession": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "predecessor_execution_id", "successor_model", "demonstration", "requested_authority"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "predecessor_execution_id": { "$ref": "#/components/schemas/Uuid" }, "successor_model": { "type": "string", "minLength": 1, "maxLength": 200 }, "demonstration": { "type": "object", "x-max-canonical-json-bytes": 16384 }, "requested_authority": { "type": "object", "x-max-canonical-json-bytes": 16384 } } }, "ReviewSuccession": { "type": "object", "additionalProperties": false, "required": ["expected_revision", "verdict", "reason", "evidence_revisions"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "verdict": { "type": "string", "enum": ["qualified", "rejected"] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidence_revisions": { "$ref": "#/components/schemas/EvidenceRevisions", "minItems": 1 } } }, "Succession": { "type": "object", "additionalProperties": false, "required": ["id", "orchestration_id", "predecessor_execution_id", "successor_execution_id", "role_id", "proposed_by_key_id", "created_revision", "demonstration", "requested_authority", "status", "reviewed_by_key_id", "review_revision", "review_reason", "evidence_revisions", "granted_authority", "created_at", "reviewed_at"], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "orchestration_id": { "$ref": "#/components/schemas/Uuid" }, "predecessor_execution_id": { "$ref": "#/components/schemas/Uuid" }, "successor_execution_id": { "$ref": "#/components/schemas/Uuid" }, "role_id": { "$ref": "#/components/schemas/Uuid" }, "proposed_by_key_id": { "$ref": "#/components/schemas/Uuid" }, "created_revision": { "$ref": "#/components/schemas/Revision" }, "demonstration": { "type": "object" }, "requested_authority": { "type": "object" }, "status": { "type": "string", "enum": ["demonstrating", "qualified", "rejected"] }, "reviewed_by_key_id": { "anyOf": [{ "$ref": "#/components/schemas/Uuid" }, { "type": "null" }] }, "review_revision": { "anyOf": [{ "$ref": "#/components/schemas/Revision" }, { "type": "null" }] }, "review_reason": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "evidence_revisions": { "anyOf": [{ "$ref": "#/components/schemas/EvidenceRevisions" }, { "type": "null" }] }, "granted_authority": { "anyOf": [{ "type": "object" }, { "type": "null" }] }, "created_at": { "type": "string", "format": "date-time" }, "reviewed_at": { "anyOf": [{ "type": "string", "format": "date-time" }, { "type": "null" }] } } }, "LifecycleTransition": { "type": "object", "additionalProperties": false, "required": ["expected_revision"], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000, "default": "Application requested lifecycle transition." } } }, "Usage": { "type": "object", "additionalProperties": false, "required": ["window", "limits", "usage"], "properties": { "window": { "type": "object", "additionalProperties": false, "required": ["starts_at", "ends_at"], "properties": { "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" } } }, "limits": { "type": "object", "additionalProperties": false, "required": ["orchestrations", "execution_requests", "accounted_tokens"], "properties": { "orchestrations": { "type": "integer", "minimum": 1 }, "execution_requests": { "type": "integer", "minimum": 1 }, "accounted_tokens": { "type": "integer", "minimum": 1 } } }, "usage": { "type": "object", "additionalProperties": false, "required": ["orchestrations", "execution_requests", "accounted_tokens", "known_input_tokens", "known_output_tokens", "reported_cost_usd", "held_reservations"], "properties": { "orchestrations": { "type": "integer", "minimum": 0 }, "execution_requests": { "type": "integer", "minimum": 0 }, "accounted_tokens": { "type": "integer", "minimum": 0 }, "known_input_tokens": { "type": "integer", "minimum": 0 }, "known_output_tokens": { "type": "integer", "minimum": 0 }, "reported_cost_usd": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{8}$" }, "held_reservations": { "type": "integer", "minimum": 0 } } } } }, "Orchestration": { "type": "object", "additionalProperties": false, "required": ["id", "client_reference", "revision", "initial_state", "instructions", "metadata", "status", "role_policy", "root_role_id", "status_changed_at", "created_at"], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "client_reference": { "anyOf": [{ "$ref": "#/components/schemas/ClientReference" }, { "type": "null" }] }, "revision": { "$ref": "#/components/schemas/Revision" }, "initial_state": {}, "instructions": { "type": "string" }, "metadata": {}, "status": { "type": "string", "enum": ["active", "paused", "cancelled"] }, "role_policy": { "$ref": "#/components/schemas/RolePolicy" }, "root_role_id": { "$ref": "#/components/schemas/Uuid" }, "status_changed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Event": { "type": "object", "additionalProperties": false, "required": ["revision", "kind", "payload", "created_at"], "properties": { "revision": { "$ref": "#/components/schemas/Revision" }, "kind": { "type": "string" }, "payload": {}, "created_at": { "type": "string", "format": "date-time" } } }, "ResumableExportManifest": { "type": "object", "additionalProperties": false, "required": ["format", "version", "orchestration_id", "through_revision", "export_id", "generated_at", "expires_at", "content_sha256", "byte_count", "chunk_count", "row_counts", "chunks"], "properties": { "format": { "const": "persistent-orchestration-chunked-export" }, "version": { "const": 2 }, "orchestration_id": { "$ref": "#/components/schemas/Uuid" }, "through_revision": { "$ref": "#/components/schemas/Revision" }, "export_id": { "$ref": "#/components/schemas/Uuid" }, "generated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "content_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "byte_count": { "type": "integer", "minimum": 1 }, "chunk_count": { "type": "integer", "minimum": 1 }, "row_counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "chunks": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["chunk_index", "content_sha256", "byte_count"], "properties": { "chunk_index": { "type": "integer", "minimum": 0 }, "content_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "byte_count": { "type": "integer", "minimum": 1, "maximum": 524288 } } } } } }, "ResumableExportChunk": { "type": "object", "additionalProperties": false, "required": ["orchestration_id", "export_id", "chunk_index", "chunk_count", "content_base64", "content_sha256", "byte_count", "expires_at"], "properties": { "orchestration_id": { "$ref": "#/components/schemas/Uuid" }, "export_id": { "$ref": "#/components/schemas/Uuid" }, "chunk_index": { "type": "integer", "minimum": 0 }, "chunk_count": { "type": "integer", "minimum": 1 }, "content_base64": { "type": "string", "contentEncoding": "base64" }, "content_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "byte_count": { "type": "integer", "minimum": 1, "maximum": 524288 }, "expires_at": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "object", "additionalProperties": false, "required": ["code"], "properties": { "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } } } } } } } }