{ "openapi": "3.1.0", "info": { "title": "delta mandate Orchestrator API", "description": "API for submitting signed intents, proposing solutions, and managing templates. The Orchestrator verifies each proposal against the user's signed intent and the configured template.", "license": { "name": "delta mandate Evaluation License", "url": "/license" }, "version": "0.5.1" }, "paths": { "/config": { "get": { "tags": [ "config" ], "description": "Get the runtime configuration.", "operationId": "config_get", "responses": { "200": { "description": "Runtime configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeConfigResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "config" ], "description": "Set the runtime configuration.", "operationId": "config_set", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRuntimeConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "Runtime configuration updated" }, "400": { "description": "Invalid evidence extractor URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/events": { "get": { "tags": [ "events" ], "description": "Server-Sent Events stream of orchestrator events. Each event's data is one JSON-encoded OrchestratorEvent.", "operationId": "events_stream", "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 a signed intent.\n\nThe signature is verified and the referenced template must exist before the intent is stored.", "operationId": "intents_submit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseSignedMessage" } } }, "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/BaseSignedMessage" } } } }, "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 template must exist and the intent must not yet have a proposal. Evidence will be extracted from the proposed solution, then validated against the template 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" } } } } } } }, "/templates": { "post": { "tags": [ "templates" ], "description": "Compile, validate, and store a template from its source.\n\nThe compiled template is content-addressed by its SHA-256 hash, so submitting the same source twice returns the same template ID.", "operationId": "templates_submit", "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Template created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateResponse" } } } }, "400": { "description": "Compilation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/templates/validate": { "post": { "tags": [ "templates" ], "description": "Compile and validate a template from its source without storing it.\n\nThis performs the same compilation validation as template submission, but does not create a template ID or write the compiled template to storage.", "operationId": "templates_validate", "requestBody": { "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Template is valid" }, "400": { "description": "Compilation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/templates/{template_id}": { "get": { "tags": [ "templates" ], "description": "Get a human-readable pretty-printed representation of a stored template.", "operationId": "templates_get", "parameters": [ { "name": "template_id", "in": "path", "description": "Template ID", "required": true, "schema": { "$ref": "#/components/schemas/HashDigest" } } ], "responses": { "200": { "description": "Template pretty-print found", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "templates" ], "description": "Delete a stored template by its ID.", "operationId": "templates_delete", "parameters": [ { "name": "template_id", "in": "path", "description": "Template ID", "required": true, "schema": { "$ref": "#/components/schemas/HashDigest" } } ], "responses": { "200": { "description": "Template deleted" }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "BaseSignedMessage": { "type": "object", "description": "A user-signed message", "required": [ "payload", "signature" ], "properties": { "payload": { "$ref": "#/components/schemas/Intent", "description": "The data payload that is being signed." }, "signature": { "$ref": "#/components/schemas/Signature", "description": "The signature corresponding to the above." } } }, "ConstraintFailure": { "type": "object", "description": "A failed constraint of the template", "required": [ "index", "pretty_expr", "reason" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "pretty_expr": { "type": "string" }, "reason": { "type": "string" } } }, "CreateTemplateResponse": { "type": "object", "description": "Response returned when a template is successfully created.", "required": [ "template_id" ], "properties": { "template_id": { "$ref": "#/components/schemas/HashDigest", "description": "Content-addressed ID of the stored template (base58-encoded SHA-256 of the compiled template bytes)." } } }, "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)" }, "InputMap": { "type": "object", "description": "A runtime input container mapping field names to their values.", "required": [ "fields" ], "properties": { "fields": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } } } }, "Intent": { "type": "object", "description": "A user's expression of intent: a template instantiated with concrete\nattribute values.\n\nThe intent specifies what the user wants to happen (`template_id`) and the\nconstraints on how it may be fulfilled (`attrs`). Intents are always\nsubmitted as a `SignedIntent` to prove authorship.", "required": [ "id", "attrs", "template_id" ], "properties": { "attrs": { "$ref": "#/components/schemas/InputMap", "description": "Attribute values that parameterize the template." }, "id": { "$ref": "#/components/schemas/IntentId", "description": "Unique identifier for this intent." }, "template_id": { "$ref": "#/components/schemas/HashDigest", "description": "ID of the template that defines the rules for fulfilling this intent." } } }, "IntentId": { "type": "string", "format": "uuid", "description": "Unique identifier for an intent, assigned by the caller." }, "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" } } }, "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", "evidence", "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, or null 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 extract\nevidence, then runs ZK proof generation to verify the proposal satisfies the intent's\ntemplate constraints.", "required": [ "solution", "metadata" ], "properties": { "metadata": { "description": "Additional metadata shared with the evidence layer.\n\nThe content is agreed between the template provider and evidence layer." }, "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 template provider and evidence layer." } } }, "RuntimeConfigResponse": { "type": "object", "description": "Runtime configuration", "required": [ "evidence_extractor_url" ], "properties": { "evidence_extractor_url": { "type": "string", "description": "Base URL of the configured evidence extractor." } } }, "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." }, "UpdateRuntimeConfigRequest": { "type": "object", "description": "Runtime configuration update", "required": [ "evidence_extractor_url" ], "properties": { "evidence_extractor_url": { "type": "string", "description": "New base URL of the evidence extractor service or the empty string to\nuse the default." } } }, "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 compiled template. Submitting a proposal triggers ZK proof generation to verify the solution satisfies the policy defined by the intent and its template." }, { "name": "templates", "description": "Upload and delete compiled templates.\n\nTemplates define the rules that intents and proposals must satisfy." }, { "name": "config", "description": "Read and update operator-facing runtime configuration." }, { "name": "events", "description": "Stream live orchestrator events to downstream clients." } ] }