{ "openapi": "3.1.0", "info": { "title": "RuleEvo Control API", "version": "0.3.0", "description": "Deterministic delegated authority, stable effect admission and execution evidence. REST, SDK and MCP share the same core. No provider execution in the hosted canonical effect service. UNKNOWN is unresolved; withdrawal does not undo completed effects. Owner-private access and existing APIs remain supported. Live billing stays gated." }, "servers": [ { "url": "/api/v1" } ], "security": [ { "actorBearer": [], "privateSiteAccess": [] }, { "ownerSession": [] } ], "components": { "securitySchemes": { "actorBearer": { "type": "http", "scheme": "bearer", "description": "RuleEvo actor key; keep server-side." }, "privateSiteAccess": { "type": "apiKey", "in": "header", "name": "OAI-Sites-Authorization", "description": "Bearer ; send only to this Site." }, "ownerSession": { "type": "apiKey", "in": "cookie", "name": "platform-managed-session", "description": "Conceptual owner session managed by Sites dispatch. This is not a literal cookie name or user-settable identity header." } }, "schemas": { "PilotDraftData": { "type": "object", "required": [ "company" ], "properties": { "company": { "type": "string", "maxLength": 160 }, "contact_url": { "type": "string", "maxLength": 500 }, "workflow": { "type": "string", "maxLength": 2000 }, "technical_owner": { "type": "string", "maxLength": 160 }, "feedback_note": { "type": "string", "maxLength": 2000 }, "notes": { "type": "string", "maxLength": 4000 }, "monthly_actions": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "spend_ceiling_usd": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 10 }, "support_hours": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0 }, "retention_days": { "type": "integer", "minimum": 0, "maximum": 365, "default": 30 }, "pricing_feedback": { "enum": [ "unknown", "interested", "needs_revision", "declined" ] }, "checks": { "type": "object", "properties": { "sponsor": { "type": "string", "maxLength": 1200 }, "scope": { "type": "string", "maxLength": 1200 }, "integration": { "type": "string", "maxLength": 1200 }, "sandbox": { "type": "string", "maxLength": 1200 }, "acceptance": { "type": "string", "maxLength": 1200 }, "commercial": { "type": "string", "maxLength": 1200 }, "support": { "type": "string", "maxLength": 1200 }, "security": { "type": "string", "maxLength": 1200 } }, "additionalProperties": false }, "archived": { "type": "boolean" } }, "additionalProperties": false }, "EffectProposal": { "type": "object", "required": [ "grant_id", "idempotency_key", "operation", "provider", "resource_type", "resource", "payload_digest", "environment" ], "properties": { "grant_id": { "type": "string" }, "effect_id": { "type": "string", "pattern": "^eff_[A-Za-z0-9_-]{8,80}$" }, "idempotency_key": { "type": "string", "maxLength": 100 }, "operation": { "type": "string", "maxLength": 64 }, "provider": { "type": "string", "maxLength": 80 }, "resource_type": { "type": "string", "maxLength": 80 }, "resource": { "type": "string", "maxLength": 500 }, "payload_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "environment": { "enum": [ "sandbox", "live" ] }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 100000000, "default": 0 }, "currency": { "enum": [ "USD" ], "default": "USD" }, "consequence": { "enum": [ "protected_write" ] } }, "description": "One stable intended external effect. Send only the canonical payload digest; keep payload and credentials with the trusted adapter. Reusing a key with changed facts conflicts." }, "AuthorityBinding": { "type": "object", "required": [ "providers", "resources", "environment" ], "properties": { "providers": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20 }, "resources": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20 }, "environment": { "enum": [ "sandbox", "live" ] }, "max_amount_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 } }, "description": "Owner-only immutable exact binding. All ancestor bindings apply by intersection. First creation advances root epoch; withdraw and replace to change." }, "Effect": { "type": "object", "required": [ "effect_id", "authority_id", "state", "payload_digest", "request_key" ], "properties": { "effect_id": { "type": "string" }, "authority_id": { "type": "string" }, "mandate_id": { "type": "string" }, "actor_id": { "type": "string" }, "operation": { "type": "string" }, "provider": { "type": "string" }, "resource_type": { "type": "string" }, "resource": { "type": "string" }, "payload_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "environment": { "enum": [ "sandbox", "live" ] }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "state": { "enum": [ "proposed", "admitting", "admitted", "denied", "dispatched", "unknown", "reconciling", "completed", "failed" ] }, "admission_id": { "type": [ "string", "null" ] }, "authority_epoch": { "type": [ "integer", "null" ] }, "authority_snapshot": { "type": [ "object", "null" ] }, "request_key": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time" }, "admitted_at": { "type": [ "string", "null" ] }, "dispatched_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "last_checked_at": { "type": [ "string", "null" ] }, "provider_reference": { "type": [ "string", "null" ] }, "response_digest": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "reconciliation_count": { "type": "integer" }, "reconciliation_required": { "type": "boolean" } }, "description": "Provider facts are authenticated caller statements, not independent provider attestation. A recorded dispatch claim is not proof of receipt or completion." }, "EffectOutcome": { "type": "object", "required": [ "state", "observation_key" ], "properties": { "state": { "enum": [ "completed", "failed", "unknown" ] }, "observation_key": { "type": "string", "maxLength": 100 }, "provider_reference": { "type": "string", "maxLength": 300 }, "response_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "error_code": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,80}$" }, "failure_class": { "enum": [ "confirmed_no_effect" ] } }, "description": "Completion requires provider reference. Failed requires confirmed_no_effect; that classification is invalid for other states. No raw provider response or secret. Durable observation keys replay without replacing newer facts." }, "Authority": { "type": "object", "properties": { "authority_id": { "type": "string" }, "mandate_id": { "type": "string" }, "principal_id": { "type": "string" }, "owner_id": { "type": "string" }, "tenant_id": { "type": "string" }, "actor_id": { "type": "string" }, "actor_type": { "enum": [ "agent", "provider" ] }, "status": { "enum": [ "active", "revoked", "expired" ] }, "authority_epoch": { "type": "integer" }, "permitted_operations": { "type": "array", "items": { "type": "string" } }, "constraints": { "type": [ "object", "null" ] }, "ancestor_constraints": { "type": "array", "items": { "type": "object" } }, "currency": { "const": "USD" }, "budget_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "spent_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "expires_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ] }, "revocation_reason": { "type": [ "string", "null" ] }, "parent_authority_id": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "policy_version": { "type": "string" } }, "description": "Read-only projection of original grant/root, not a parallel authority store. Balance snapshots precede the separately atomic commit." } } }, "paths": { "/dashboard": { "get": { "summary": "Owner dashboard", "description": "Owner session required. Workspace data, recent events and actions, usage projections and public signing key.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } } } }, "/mandates": { "post": { "summary": "Create instruction", "description": "Owner session required. Scopes and budgets are immutable; withdrawal is permanent.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "budget_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "title", "scopes", "budget_cents" ] } } } } } }, "/mandates/{id}": { "get": { "summary": "Read instruction", "description": "Owner sees complete history. Assigned actors see the root and their own grants.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/mandates/{id}/delegate": { "post": { "summary": "Delegate narrower authority", "description": "Owners can delegate from a root. Agents require their own parent grant. Provider credentials cannot delegate.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_id": { "type": "string" }, "actor_id": { "type": "string" }, "actor_label": { "type": "string" }, "kind": { "enum": [ "agent", "provider" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "budget_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "actor_id", "actor_label", "kind", "scopes", "budget_cents" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/tasks": { "get": { "summary": "Poll own grants", "description": "Returns grants assigned to the authenticated actor and credential role. Owners see the workspace directory. effective_status includes expiry.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } } } }, "/actions/authorize": { "post": { "summary": "Request a 60-second action permit", "description": "Does not reserve budget or execute external work. New admitted permits record one projected fee. Exact retries reuse the permit; changed parameters conflict.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string" }, "operation": { "type": "string" }, "resource": { "type": "string" }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "idempotency_key": { "type": "string" } }, "required": [ "grant_id", "operation", "resource", "idempotency_key" ] } } } } } }, "/actions/{id}/commit": { "post": { "summary": "Record commit authority", "description": "Rechecks root epoch, scope ancestry, expiry and shared budgets atomically. Does not perform or verify external execution. Safe to repeat within RuleEvo.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/mandates/{id}/revoke": { "post": { "summary": "Withdraw root authority", "description": "Owner only. Invalidate pending permits; request provider acknowledgement. Does not undo committed work.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/grants/{id}/revoke": { "post": { "summary": "Withdraw branch authority", "description": "Owner only. Revokes the grant and descendants without affecting sibling grants.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/grants/{id}/acknowledge": { "post": { "summary": "Record stop evidence", "description": "Assigned provider or owner only. Explicit withdrawal required. Provider claims are attestations, not independently verified facts.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "stopped", "already_committed", "unknown" ] }, "note": { "type": "string" } }, "required": [ "status", "note" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/mandates/{id}/receipt": { "post": { "summary": "Issue signed record", "description": "Owner only. ECDSA P-256 signature over canonical JSON. Pin a trusted workspace public key to verify. Signature does not establish external truth.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/tokens": { "post": { "summary": "Create actor credential", "description": "Owner session only. 256-bit secret shown once; server stores SHA-256 hash. Default expiry 30 days.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "actor_id": { "type": "string" }, "role": { "enum": [ "agent", "provider" ] }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "label", "actor_id", "role" ] } } } } } }, "/tokens/{id}/revoke": { "post": { "summary": "Revoke actor credential", "description": "Owner only. This does not revoke independent instruction authority or stop remote work.", "responses": { "200": { "description": "Success; JSON record or collection" }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Authority, scope, actor or owner access denied" }, "409": { "description": "Idempotency conflict or stale/invalid commit" }, "429": { "description": "Pilot limit reached" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/pilot": { "get": { "summary": "List saved synthetic provider pilot runs", "responses": { "200": { "description": "Run metadata and evidence reports" } } }, "post": { "summary": "Create a zero-budget synthetic provider pilot", "responses": { "201": { "description": "Prepared run" } } } }, "/pilot/{id}": { "get": { "summary": "Read signed pilot evidence", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pilot run" } } } }, "/pilot/{id}/step": { "post": { "summary": "Advance one bounded pilot case", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pilot run" } } } }, "/pilot/{id}/abort": { "post": { "summary": "Withdraw test authority and clear injected outages", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pilot run" } } } }, "/drive": { "get": { "summary": "Inspect Drive sandbox and recent jobs", "responses": { "200": { "description": "Drive sandbox or operation state" }, "403": { "description": "Actor, scope or folder denied" }, "409": { "description": "State or authority conflict" } }, "description": "Owner only. No Google credentials or hosted connector access is granted." } }, "/drive/configure": { "post": { "summary": "Register a dedicated test folder from observed metadata", "responses": { "200": { "description": "Drive sandbox or operation state" }, "403": { "description": "Actor, scope or folder denied" }, "409": { "description": "State or authority conflict" } }, "description": "Owner only. No Google credentials or hosted connector access is granted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "type": "string" }, "folder_url": { "type": "string" }, "title": { "type": "string" }, "mime_type": { "type": "string" } }, "required": [ "folder_id", "folder_url", "title", "mime_type" ], "additionalProperties": false } } } } } }, "/drive/jobs": { "post": { "summary": "Create an idempotent fixed-folder operation", "responses": { "200": { "description": "Drive sandbox or operation state" }, "403": { "description": "Actor, scope or folder denied" }, "409": { "description": "State or authority conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_id": { "type": "string" }, "folder_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "grant_id", "folder_id", "idempotency_key", "label" ], "additionalProperties": false } } } } } }, "/drive/jobs/{id}": { "get": { "summary": "Read an assigned Drive operation", "responses": { "200": { "description": "Drive sandbox or operation state" }, "403": { "description": "Actor, scope or folder denied" }, "409": { "description": "State or authority conflict" } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "/drive/jobs/{id}/prepare": { "post": { "summary": "Precheck permission without an external effect", "responses": { "200": { "description": "Drive sandbox or operation state" }, "403": { "description": "Actor, scope or folder denied" }, "409": { "description": "State or authority conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "/drive/jobs/{id}/admit": { "post": { "summary": "Claim execution once; execute:false forbids external creation", "responses": { "200": { "description": "Drive sandbox or operation state" }, "403": { "description": "Actor, scope or folder denied" }, "409": { "description": "State or authority conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "/drive/jobs/{id}/observe": { "post": { "summary": "Record matching connector metadata; this is not a Google attestation", "responses": { "200": { "description": "Drive sandbox or operation state" }, "403": { "description": "Actor, scope or folder denied" }, "409": { "description": "State or authority conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mime_type": { "type": "string" }, "url": { "type": "string" }, "parent_ids": { "type": "array", "items": { "type": "string" } }, "trashed": { "type": "boolean" } }, "required": [ "id", "name", "mime_type", "url", "parent_ids" ], "additionalProperties": false } }, "required": [ "metadata" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "/drive/jobs/{id}/uncertain": { "post": { "summary": "Mark an ambiguous write outcome for reconciliation", "responses": { "200": { "description": "Drive sandbox or operation state" }, "403": { "description": "Actor, scope or folder denied" }, "409": { "description": "State or authority conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "/launch": { "get": { "summary": "List private pilot drafts", "responses": { "200": { "description": "Owner-only preparation record(s); no payment or activation" }, "401": { "description": "Owner identity required" }, "403": { "description": "Owner only" }, "409": { "description": "Revision, idempotency or record limit conflict" } } }, "post": { "summary": "Create an idempotent private pilot draft", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_key", "data" ], "properties": { "request_key": { "type": "string", "minLength": 1, "maxLength": 100 }, "data": { "$ref": "#/components/schemas/PilotDraftData" } } } } } }, "responses": { "200": { "description": "Owner-only preparation record(s); no payment or activation" }, "201": { "description": "Created or idempotently recovered draft" }, "401": { "description": "Owner identity required" }, "403": { "description": "Owner only" }, "409": { "description": "Revision, idempotency or record limit conflict" } } } }, "/launch/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read a private pilot draft", "responses": { "200": { "description": "Owner-only preparation record(s); no payment or activation" }, "401": { "description": "Owner identity required" }, "403": { "description": "Owner only" }, "409": { "description": "Revision, idempotency or record limit conflict" } } }, "post": { "summary": "Update with optimistic revision; does not change initial creation fingerprint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revision", "data" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "data": { "$ref": "#/components/schemas/PilotDraftData" } } } } } }, "responses": { "200": { "description": "Owner-only preparation record(s); no payment or activation" }, "401": { "description": "Owner identity required" }, "403": { "description": "Owner only" }, "409": { "description": "Revision, idempotency or record limit conflict" } } } }, "/authorities": { "get": { "summary": "List canonical authority projections", "description": "Bounded by existing task list limits, filtered by workspace and actor role.", "responses": { "200": { "description": "Bounded authenticated result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/authorities/{authorityId}": { "parameters": [ { "name": "authorityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read authority projection", "description": "Exact root epoch and immutable binding snapshot.", "responses": { "200": { "description": "Bounded authenticated result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/authorities/{authorityId}/bind": { "parameters": [ { "name": "authorityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Bind an authority to exact external targets", "description": "Owner only; first creation advances root epoch. Immutable; ancestors remain restrictive.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorityBinding" } } } }, "responses": { "200": { "description": "Recorded result. Inspect decision/state; a successful HTTP response is not external completion.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/capabilities": { "get": { "summary": "Read curated adapter capability registry", "description": "Provenance is explicit; unknown capability values never imply support.", "responses": { "200": { "description": "Bounded authenticated result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/effects": { "get": { "summary": "List effects", "description": "Latest 200 matching workspace/actor records; never infer lifetime rates from this list.", "responses": { "200": { "description": "Bounded authenticated result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "schema": { "type": "string" } }, { "name": "operation", "in": "query", "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "schema": { "type": "string" } }, { "name": "grant_id", "in": "query", "schema": { "type": "string" } }, { "name": "mandate_id", "in": "query", "schema": { "type": "string" } } ] }, "post": { "summary": "Propose one exact consequential effect", "description": "Stable actor/key identity and digest; never creates a provider action.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectProposal" } } } }, "responses": { "200": { "description": "Recorded result. Inspect decision/state; a successful HTTP response is not external completion.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/effects/{effectId}": { "parameters": [ { "name": "effectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Read one stable effect", "description": "Includes state, admission, epoch and provider reference. Unknown is distinct from failed.", "responses": { "200": { "description": "Bounded authenticated result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/effects/metrics": { "get": { "summary": "Read owner operations metrics", "description": "Whole-workspace lifetime counts; successful service-admission samples limited to latest 1000; authenticated request counter is current + previous 10 minute buckets. Billing eligibility excludes demo/unassigned/preactivation actions. Not hosted load verification.", "responses": { "200": { "description": "Bounded authenticated result.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/effects/{effectId}/admit": { "parameters": [ { "name": "effectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Evaluate and commit current authority", "description": "Deterministic existing precheck/commit. Returns admitted, decision and effect; HOLD means no execution. Retries use the same effect. Interrupted local admission is checked locally.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "authority_epoch": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Recorded result. Inspect decision/state; a successful HTTP response is not external completion.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/effects/{effectId}/dispatch": { "parameters": [ { "name": "effectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Claim external dispatch exactly once", "description": "Returns execute:true to only the winning caller, after current authority/epoch checks. Lost response never authorizes a new write; reconcile.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payload_digest" ], "properties": { "payload_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "Recorded result. Inspect decision/state; a successful HTTP response is not external completion.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/effects/{effectId}/outcome": { "parameters": [ { "name": "effectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Record a redacted adapter outcome", "description": "Only after recorded dispatch. Durable observation-key idempotency. Completed/failed/denied records are terminal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectOutcome" } } } }, "responses": { "200": { "description": "Recorded result. Inspect decision/state; a successful HTTP response is not external completion.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/effects/{effectId}/reconcile": { "parameters": [ { "name": "effectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Check local admission or begin provider readback", "description": "Returns reconcile:false for unresolved local admission or terminal state. reconcile:true permits readback only, never another execution.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Recorded result. Inspect decision/state; a successful HTTP response is not external completion.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/effects/{effectId}/evidence": { "parameters": [ { "name": "effectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Finalize signed effect evidence", "description": "Owner only; requires completed/failed/denied. Returns immutable existing ECDSA receipt shape; pin previously trusted public key. Unknown can be inspected but not finalized as settled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Recorded result. Inspect decision/state; a successful HTTP response is not external completion.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, digest, environment, currency or outcome.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing, expired or revoked authentication.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Workspace/actor/role/owner or bound constraint denial.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Resource unavailable in this workspace.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Stale authority, idempotency/observation conflict or lifecycle violation.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Authenticated actor request limit.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }