{ "openapi": "3.1.0", "info": { "title": "CarryFrame enrolled-identity API", "version": "1.0.0-pilot", "description": "Controlled synthetic pilot, not general availability. Core request schemas share the implemented orchestration handler with the separate legacy endpoint. Identity is NOT legacy API-key authentication. Human principals use the reviewed dedicated-audience ZITADEL ID token; machines use the reviewed access-token/signed-companion pair. Enrollment and current grants are required. Provisioning, admin, restore and billing-control APIs are excluded from this customer reference. Model spending needs separate approval. No availability, recovery or compliance guarantee." }, "servers": [ { "url": "https://carryframe.com/api/orchestration", "description": "Current controlled-pilot service" } ], "x-service-status": "controlled-pilot-staging-grade", "x-versioning-policy": { "uri_major": true, "incompatible_changes": "New major URI, not a silent incompatible replacement.", "pilot_change_policy": "Agree supported routes and material changes in the signed scope; contact the named sponsor before retiring their integration. No contractual notice period is established here." }, "x-max-request-body-bytes": 65536, "security": [ { "HumanIdToken": [], "TenantBoundary": [] }, { "MachineAccessToken": [], "MachineSignedCompanion": [], "TenantBoundary": [] } ], "tags": [ { "name": "Account" }, { "name": "Orchestrations" }, { "name": "Executions" }, { "name": "Records" }, { "name": "Successions" }, { "name": "Roles" }, { "name": "Lifecycle" }, { "name": "Usage" }, { "name": "Tools" } ], "paths": { "/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" } } } }, "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" }, "429": { "$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" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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" }, "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}": { "get": { "tags": [ "Orchestrations" ], "summary": "Read an orchestration", "x-required-scope": "orchestrations:read", "parameters": [ { "$ref": "#/components/parameters/OrchestrationId" } ], "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" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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." }, "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" }, "429": { "$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" } } } }, "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" }, "429": { "$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" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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" }, "413": { "$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." }, "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" }, "429": { "$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." }, "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" }, "429": { "$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" }, "429": { "$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" }, "429": { "$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. Requires an enrolled natural person; attribution does not prove personal inspection.", "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" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "HumanIdToken": [], "TenantBoundary": [] } ], "x-required-principal-kind": "natural_person" } }, "/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." }, "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" }, "429": { "$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" }, "413": { "$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" } } } }, "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" }, "429": { "$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. Requires an enrolled natural person; attribution does not prove personal inspection.", "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" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "HumanIdToken": [], "TenantBoundary": [] } ], "x-required-principal-kind": "natural_person" } }, "/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." }, "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" }, "429": { "$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." }, "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" }, "429": { "$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" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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." }, "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" }, "429": { "$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" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "HumanIdToken": [], "TenantBoundary": [] } ], "x-required-principal-kind": "natural_person", "description": " Requires an enrolled natural person; attribution does not prove personal inspection." } }, "/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" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$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" }, "429": { "$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" }, "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Read enrolled tenant ID and label", "x-required-scope": "orchestrations:read", "responses": { "200": { "description": "Tenant id and label." }, "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" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/account/usage": { "get": { "tags": [ "Account" ], "summary": "Read enrolled tenant usage and limits", "x-required-scope": "orchestrations:read", "responses": { "200": { "description": "Current usage, not an invoice." }, "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" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/account/memberships": { "get": { "tags": [ "Account" ], "summary": "Discover assigned organisations", "description": "Sign-in does not create membership. Tenant header is not required for discovery. Use returned pagination cursor.", "security": [ { "HumanIdToken": [] }, { "MachineAccessToken": [], "MachineSignedCompanion": [] } ], "parameters": [ { "in": "query", "name": "after", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authorised memberships and optional next_cursor." }, "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" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/audit-export": { "get": { "tags": [ "Orchestrations" ], "summary": "Export one signed, chained snapshot", "x-required-scope": "orchestrations:read", "parameters": [ { "$ref": "#/components/parameters/OrchestrationId" } ], "description": "See the published audit schema and offline verifier. Current builder refuses exports exceeding 16 MiB, never silently truncates. Authenticate the public key independently. No proof of outside-path completeness or content truth.", "responses": { "200": { "description": "Signed carryframe-json-v1 envelope; /audit/reviewer-179b46ccf9df3b99/schema.json." }, "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" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/audit/verification-key": { "get": { "tags": [ "Orchestrations" ], "summary": "Public signing-key metadata", "security": [], "description": "Not the private key. Authenticate the expected fingerprint independently of an untrusted export.", "responses": { "200": { "description": "Verification metadata." }, "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" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/tool-invocations": { "post": { "tags": [ "Tools" ], "summary": "Admit an invocation through the qualified agentgateway path", "description": "Only one configured reference echo tool is qualified. Requires a current context execution and role with tool authority. Durable intent precedes dispatch; same-key retry reconciles without redispatch. No universal exactly-once external-effect guarantee.", "x-required-scopes": [ "orchestrations:read", "executions:write" ], "parameters": [ { "$ref": "#/components/parameters/OrchestrationId" }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_revision", "role_id", "context_execution_id", "tool_name", "arguments" ], "properties": { "expected_revision": { "$ref": "#/components/schemas/Revision" }, "role_id": { "$ref": "#/components/schemas/Uuid" }, "context_execution_id": { "$ref": "#/components/schemas/Uuid" }, "tool_name": { "type": "string", "description": "Operator-configured name; not client tool registration." }, "arguments": { "type": "object", "x-max-utf8-bytes": 32768 } } } } } }, "responses": { "200": { "description": "Observed/not-dispatched or reconciled terminal disposition; inspect status." }, "202": { "description": "Pending or uncertain, not a success assertion." }, "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" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orchestrations/{orchestrationId}/tool-invocations/{invocationId}": { "get": { "tags": [ "Tools" ], "summary": "Read recorded intent/outcome without redispatch", "x-required-scope": "orchestrations:read", "description": "After the observation deadline, a read may persist an explicit uncertain outcome. It never resends the tool call.", "parameters": [ { "$ref": "#/components/parameters/OrchestrationId" }, { "in": "path", "name": "invocationId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "responses": { "200": { "description": "Recorded terminal disposition." }, "202": { "description": "Pending or uncertain." }, "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" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "HumanIdToken": { "type": "http", "scheme": "bearer", "bearerFormat": "Reviewed ZITADEL OIDC ID JWT", "description": "Enrolled natural-person subject, dedicated audience and current tenant authority. Not a Supabase token or por_v1 key." }, "MachineAccessToken": { "type": "http", "scheme": "bearer", "description": "Reviewed ZITADEL client-credentials access token; requires the signed companion and enrolled subject/client/service grant." }, "MachineSignedCompanion": { "type": "apiKey", "in": "header", "name": "X-CarryFrame-Machine-ID-Token", "description": "Issuer-signed companion; provider-specific token-pair profile, not an RFC 9068 claim." }, "TenantBoundary": { "type": "apiKey", "in": "header", "name": "X-CarryFrame-Tenant", "description": "Enrolled tenant UUID; selector only, not authority." } }, "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" }, "operator_identity": { "anyOf": [ { "$ref": "#/components/schemas/OperatorIdentity" }, { "type": "null" } ] }, "operator_request_id": { "anyOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] } } }, "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_]*$" } } } } }, "OperatorIdentity": { "type": "object", "properties": { "principal_id": { "type": "string" }, "issuer": { "type": "string" }, "subject": { "type": "string" }, "token_id": { "type": "string" }, "token_id_source": { "type": "string" }, "authenticated_at": { "type": "string" }, "principal_kind": { "type": "string" }, "token_profile": { "type": "string" }, "expires_at": { "type": "string" }, "authentication_time_source": { "type": "string" }, "companion_token_sha256": { "type": "string" }, "authority_source": { "type": "string" } }, "description": "Server-established identity evidence, never caller-selected actor or raw credential." } } }, "x-availability-and-recovery": { "sla": false, "rpo_guaranteed": false, "rto_guaranteed": false }, "x-client-rules": { "public_signup": false, "legacy_api_keys_accepted": false, "machine_reviews_allowed": false, "usage": "Read current tenant limits; no automatic overages.", "uncertain_delivery": "Hold and reconcile without blind redispatch. Preserve the exact request and original idempotency key." } }