{ "openapi": "3.1.0", "info": { "title": "delta mandate Orchestrator API", "description": "API for submitting intents, proposing solutions, and managing policies. The Orchestrator verifies each proposal against the user's intent and policy.", "license": { "name": "delta mandate Evaluation License", "url": "/license" }, "version": "0.9.4" }, "paths": { "/events": { "get": { "tags": [ "events" ], "description": "Server-Sent Events stream of orchestrator events. Each event's data is one JSON-encoded OrchestratorEvent.", "operationId": "events_stream", "parameters": [ { "name": "last-event-id", "in": "header", "description": "SSE Last-Event-ID header; omitting it replays all retained events.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "One JSON-encoded OrchestratorEvent per SSE event.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/OrchestratorEvent" } } } } } } }, "/intents": { "post": { "tags": [ "intents" ], "description": "Submit an intent and its authorship.\n\nThe authorship is verified (a signature when present; unsigned intents are accepted where the orchestrator permits it) and the referenced policy must exist before the intent is stored.", "operationId": "intents_submit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoredIntent" } } }, "required": true }, "responses": { "200": { "description": "Intent accepted" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Intent already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/intents/{intent_id}": { "get": { "tags": [ "intents" ], "description": "Get a stored intent by its ID.", "operationId": "intents_get", "parameters": [ { "name": "intent_id", "in": "path", "description": "Intent ID", "required": true, "schema": { "$ref": "#/components/schemas/IntentId" } } ], "responses": { "200": { "description": "Intent found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoredIntent" } } } }, "404": { "description": "Intent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/intents/{intent_id}/proposal": { "post": { "tags": [ "intents" ], "description": "Submit a proposal for a pending intent, triggering the delta mandate pipeline.\n\nThe intent and its policy must exist and the intent must not yet have a proposal. Evidence will be extracted from the proposed solution, then validated against the policy and intent. Upon success, a proof is generated.", "operationId": "intents_propose", "parameters": [ { "name": "intent_id", "in": "path", "description": "Intent ID", "required": true, "schema": { "$ref": "#/components/schemas/IntentId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proposal" } } }, "required": true }, "responses": { "200": { "description": "Proposal accepted, proving started" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Intent already has a proposal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Processing capacity exceeded, retry later", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/intents/{intent_id}/status": { "get": { "tags": [ "intents" ], "description": "Get the current status of an intent.", "operationId": "intents_status", "parameters": [ { "name": "intent_id", "in": "path", "description": "Intent ID", "required": true, "schema": { "$ref": "#/components/schemas/IntentId" } } ], "responses": { "200": { "description": "Intent status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntentStatus" } } } }, "404": { "description": "Intent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/policies": { "post": { "tags": [ "policies" ], "description": "Compile, validate, and store a policy from its source.\n\nThe compiled policy is content-addressed by the SHA-256 hash of its compiled bytecode; submitting the same source twice returns the same ID.", "operationId": "policies_submit", "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HashDigest" } } } }, "400": { "description": "Compilation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/policies/{policy_id}": { "get": { "tags": [ "policies" ], "description": "Get a human-readable pretty-printed representation of a stored policy.", "operationId": "policies_get", "parameters": [ { "name": "policy_id", "in": "path", "description": "Policy ID", "required": true, "schema": { "$ref": "#/components/schemas/HashDigest" } } ], "responses": { "200": { "description": "Policy pretty-print", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Policy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "policies" ], "description": "Delete a stored policy by its ID.", "operationId": "policies_delete", "parameters": [ { "name": "policy_id", "in": "path", "description": "Policy ID", "required": true, "schema": { "$ref": "#/components/schemas/HashDigest" } } ], "responses": { "200": { "description": "Policy deleted" }, "404": { "description": "Policy not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Policy is referenced by open intents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "AuthoredIntent": { "type": "object", "description": "An intent together with its [`Authorship`].\n\nWhen signed, the signature is over the JCS (JSON Canonicalization Scheme,\nRFC 8785) serialization of the `intent`. A signer serializes the intent with\nJCS and signs those bytes, for instance in TypeScript:\n\n```ts\nimport canonicalize from \"canonicalize\";\n\nconst jcs = canonicalize(json_intent)\nconst bytes = new TextEncoder().encode(jcs)\nconst signed = signer.signBytes(bytes)\n```", "required": [ "intent", "authorship" ], "properties": { "authorship": { "$ref": "#/components/schemas/Authorship", "description": "How the intent is authorized." }, "intent": { "$ref": "#/components/schemas/Intent", "description": "The intent that is being authorized." } } }, "Authorship": { "oneOf": [ { "type": "object", "description": "A signature over the JCS serialization of the intent.", "required": [ "Signed" ], "properties": { "Signed": { "$ref": "#/components/schemas/Signature", "description": "A signature over the JCS serialization of the intent." } } }, { "type": "string", "description": "No signature; authorship is not cryptographically asserted.", "enum": [ "Unsigned" ] } ], "description": "How an [`Intent`] is authorized.\n\n`Signed` carries a signature over the intent, checked by\n[`AuthoredIntent::verify_authorship`]. `Unsigned` asserts no cryptographic\nauthorship and always verifies; orchestrators that do not require signed\nintents accept it." }, "ConstraintFailure": { "type": "object", "description": "A failed constraint of the policy", "required": [ "index", "pretty_expr", "reason" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "pretty_expr": { "type": "string" }, "reason": { "type": "string" } } }, "EcdsaPubKey": { "type": "string", "description": "ECDSA Public Key" }, "EcdsaSignature": { "type": "string", "description": "ECDSA signature" }, "Ed25519PubKey": { "type": "string", "description": "Base58-encoded Ed25519 public key (32 bytes)" }, "Ed25519Scheme": { "type": "object", "description": "Represents an Ed25519 signature with its public signer", "required": [ "pub_key", "signature" ], "properties": { "pub_key": { "$ref": "#/components/schemas/Ed25519PubKey", "description": "The [PubKey] of the signer" }, "signature": { "$ref": "#/components/schemas/Ed25519Signature", "description": "The [Signature]" } } }, "Ed25519Signature": { "type": "string", "description": "Base58-encoded Ed25519 signature bytes (64 bytes)" }, "ErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "HashDigest": { "type": "string", "description": "Base58-encoded SHA-256 hash digest (32 bytes)" }, "Intent": { "type": "object", "description": "A user's expression of intent.\n\nThe intent specifies what the user wants to happen (`policy_id`) and the\nconstraints on how it may be fulfilled (`attrs`). Intents are always\nsubmitted as an `AuthoredIntent` to prove authorship.", "required": [ "id", "policy_id" ], "properties": { "attrs": { "$ref": "#/components/schemas/ObjectValue", "description": "Attribute values that parameterize the policy.\n\nIn JSON, omit this field instead of putting `\"attrs\": null`." }, "id": { "$ref": "#/components/schemas/IntentId", "description": "Unique identifier for this intent." }, "policy_id": { "$ref": "#/components/schemas/HashDigest", "description": "ID of the policy that defines the rules for fulfilling this intent." } } }, "IntentId": { "type": "string", "format": "uuid", "description": "Unique identifier for an intent, assigned by the caller." }, "IntentStatus": { "oneOf": [ { "type": "object", "description": "Intent is awaiting proposal", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open" ] } } }, { "type": "object", "description": "Intent has proposal and is being processed", "required": [ "proposal", "status" ], "properties": { "proposal": { "$ref": "#/components/schemas/Proposal", "description": "Proposal currently being processed." }, "status": { "type": "string", "enum": [ "processing" ] } } }, { "type": "object", "description": "Intent was proven (terminal)", "required": [ "intent_id", "proposal", "evidence", "status" ], "properties": { "evidence": { "type": "object", "description": "Evidence used by proof generation, as a plain JSON object." }, "intent_id": { "$ref": "#/components/schemas/IntentId", "description": "Intent that successfully completed proof generation." }, "proposal": { "$ref": "#/components/schemas/Proposal", "description": "Proposal that produced the proof." }, "status": { "type": "string", "enum": [ "success" ] } } }, { "type": "object", "description": "Intent failed to prove (terminal)", "required": [ "intent_id", "reason", "proposal", "constraint_failures", "status" ], "properties": { "constraint_failures": { "type": "array", "items": { "$ref": "#/components/schemas/ConstraintFailure" }, "description": "If the failure is caused by constraint violations, this points to the\nrelevant constraints." }, "evidence": { "type": "object", "description": "Evidence extracted before the failure as a plain JSON object, omitted if none existed." }, "intent_id": { "$ref": "#/components/schemas/IntentId", "description": "Intent that failed evidence extraction or proof generation." }, "proposal": { "$ref": "#/components/schemas/Proposal", "description": "Proposal that was being processed when the failure occurred." }, "reason": { "type": "string", "description": "Human-readable failure reason." }, "status": { "type": "string", "enum": [ "failure" ] } } }, { "type": "object", "description": "Intent expired (terminal)", "required": [ "intent_id", "status" ], "properties": { "intent_id": { "$ref": "#/components/schemas/IntentId", "description": "Intent that expired before receiving a proposal." }, "status": { "type": "string", "enum": [ "expired" ] } } } ], "description": "Current status of an intent." }, "MultisigPubKey": { "type": "object", "description": "Represents the public parameters of a multisignature authotization policy.\n\nDefines the weight each key is associated with, and the minimal threshold\nabove which a subset of signers can emit a valid signature.\n\nEach [PubKey] defines a unique owner.", "required": [ "signers", "threshold" ], "properties": { "signers": { "type": "object", "description": "The list of signers and their associated weight" }, "threshold": { "$ref": "#/components/schemas/u64", "description": "The threshold above which a subset of the signers can emit a valid signature" } } }, "MultisigScheme": { "type": "object", "description": "Multisignature scheme: a set of individual signatures collectively satisfying a threshold policy.", "required": [ "signatures", "pub_key" ], "properties": { "pub_key": { "$ref": "#/components/schemas/MultisigPubKey", "description": "The multisig descriptor to be checked against" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/Signature" }, "description": "The list of signatures" } } }, "ObjectValue": { "type": "object", "description": "A runtime object value: a map of field names to values. Also the container\nfor the parameters and evidence inputs.", "required": [ "fields" ], "properties": { "fields": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "OrchestratorEvent": { "oneOf": [ { "type": "object", "required": [ "intent_id", "proposal", "evidence", "type" ], "properties": { "evidence": { "type": "object", "description": "Evidence used by proof generation, as a plain JSON object." }, "intent_id": { "$ref": "#/components/schemas/IntentId", "description": "Intent that successfully completed proof generation." }, "proposal": { "$ref": "#/components/schemas/Proposal", "description": "Proposal that produced the proof." }, "type": { "type": "string", "enum": [ "success" ] } } }, { "type": "object", "required": [ "intent_id", "reason", "proposal", "constraint_failures", "type" ], "properties": { "constraint_failures": { "type": "array", "items": { "$ref": "#/components/schemas/ConstraintFailure" }, "description": "If the failure is caused by constraint violations, this points to the\nrelevant constraints." }, "evidence": { "type": "object", "description": "Evidence extracted before the failure as a plain JSON object, omitted if none existed." }, "intent_id": { "$ref": "#/components/schemas/IntentId", "description": "Intent that failed evidence extraction or proof generation." }, "proposal": { "$ref": "#/components/schemas/Proposal", "description": "Proposal that was being processed when the failure occurred." }, "reason": { "type": "string", "description": "Human-readable failure reason." }, "type": { "type": "string", "enum": [ "failure" ] } } }, { "type": "object", "required": [ "intent_id", "type" ], "properties": { "intent_id": { "$ref": "#/components/schemas/IntentId", "description": "Intent that expired before receiving a proposal." }, "type": { "type": "string", "enum": [ "expired" ] } } } ] }, "PasskeyScheme": { "type": "object", "description": "Signature signed by a passkey (signer) device", "required": [ "pub_key", "signature", "client_data", "authenticator_data" ], "properties": { "authenticator_data": { "type": "string", "description": "The bs58-encoded bytes of the [authenticator\ndata](https://www.w3.org/TR/webauthn-3/#authenticator-data)." }, "client_data": { "type": "string", "description": "String containing the [client data] JSON.\n\nThis field is a string because JSON does not define property order, and\nwe must guarantee that the UTF8 bytes of this string are exactly the\nsame as those used by the passkey device.\n\n[client data]: https://www.w3.org/TR/webauthn-3/#dictdef-collectedclientdata" }, "pub_key": { "$ref": "#/components/schemas/EcdsaPubKey" }, "signature": { "$ref": "#/components/schemas/EcdsaSignature" } } }, "Proposal": { "type": "object", "description": "An agent's proposed solution for a specific intent.\n\nOnce submitted, the Orchestrator sends the solution to the evidence layer to\nextract evidence, then runs proof generation to verify the proposal\nsatisfies the intent's policy constraints.", "required": [ "solution" ], "properties": { "solution": { "type": "string", "description": "Identifier of the proposed solution.\n\nExamples include a URL, a UCP product variant ID, or another identifier\nagreed between the proposal author and evidence layer." } } }, "Signature": { "oneOf": [ { "type": "object", "description": "Ed25519 signature", "required": [ "Ed25519" ], "properties": { "Ed25519": { "$ref": "#/components/schemas/Ed25519Scheme", "description": "Ed25519 signature" } } }, { "type": "object", "description": "Passkey signature", "required": [ "Passkey" ], "properties": { "Passkey": { "$ref": "#/components/schemas/PasskeyScheme", "description": "Passkey signature" } } }, { "type": "object", "description": "Multisig signature", "required": [ "Multisig" ], "properties": { "Multisig": { "$ref": "#/components/schemas/MultisigScheme", "description": "Multisig signature" } } } ], "description": "A generic verifiable signature.\n\nEach variant contains a specific signature scheme, which itself contains all the necessary\ndata to verify the signature." }, "u64": { "type": "integer", "format": "int64", "minimum": 0 } } }, "tags": [ { "name": "intents", "description": "Submit and retrieve signed user intents, and propose solutions for them.\n\nAn intent encodes what a user wants to happen, parameterized against a policy. Submitting a proposal triggers proof generation to verify the solution satisfies the intent and its policy." }, { "name": "policies", "description": "Validate, store and delete policies.\n\nPolicies define the rules that intents and proposals must satisfy." }, { "name": "events", "description": "Stream live orchestrator events to downstream clients." } ] }