{ "openapi": "3.1.0", "info": { "title": "Paygente API", "version": "0.1.0", "summary": "Programmable payment mandates for AI agents.", "description": "Paygente is an authorization layer. An agent proposes a payment; a deterministic\npolicy engine decides whether it is permitted; a person approves it when the policy\nsays a person must; and an execution rail carries it out exactly once.\n\n**This release is a sandbox.** No funds are held, no keys are custodied, no\nblockchain or payment provider is contacted, and no card is issued. Every payment\nis executed by a simulated rail and every mandate and payment attempt is returned\nwith `\"simulated\": true`. Paygente is not licensed, not regulated and not approved;\nproduction execution is intended to be delegated to licensed partners through\nadapters. See /docs/regulatory-boundary.\n\n**Money is never a JSON number.** Amounts appear as `amountMinor` (integer minor\nunits, as a string), `amount` (exact decimal) and `amountDisplay` (for people).", "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.paygente.com", "description": "Sandbox" } ], "tags": [ { "name": "Spend requests", "description": "Shadow Mode: what policy would have decided, recorded without deciding it. No endpoint under this tag moves value, and none of them can produce a mandate." }, { "name": "Mandates", "description": "The primary object: a bounded permission to pay." }, { "name": "Agents", "description": "Named principals that may propose payments." }, { "name": "Recipients", "description": "Destinations a payment is allowed to reach." }, { "name": "Policies", "description": "The rules that bound an agent’s authority." }, { "name": "Audit", "description": "The append-only record of what happened." }, { "name": "Organization", "description": "Settings and the execution kill switch." } ], "security": [ { "localDevelopmentIdentity": [] } ], "paths": { "/api/v1/agents": { "get": { "tags": [ "Agents" ], "summary": "List agents", "operationId": "listAgents", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of agents.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "hasMore", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Agents" ], "summary": "Register an agent", "description": "Registering an agent grants no authority by itself and returns no credential. Authority comes from the policy attached to it.", "operationId": "createAgent", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "201": { "description": "The agent was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/recipients": { "get": { "tags": [ "Recipients" ], "summary": "List recipients", "operationId": "listRecipients", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "verificationStatus", "in": "query", "schema": { "type": "string", "enum": [ "UNVERIFIED", "PENDING", "VERIFIED", "REJECTED" ] } }, { "name": "riskLevel", "in": "query", "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } ], "responses": { "200": { "description": "A page of recipients.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "hasMore", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Recipients" ], "summary": "Register a recipient", "operationId": "createRecipient", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipientRequest" } } } }, "responses": { "201": { "description": "The recipient was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recipient" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/policies": { "get": { "tags": [ "Policies" ], "summary": "List policies", "operationId": "listPolicies", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of policies.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "hasMore", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Policies" ], "summary": "Create a policy", "description": "A policy is data, not code. The rule set is closed: there is no expression language, so a policy can never execute.", "operationId": "createPolicy", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyRequest" } } } }, "responses": { "201": { "description": "The policy was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/spend-intents": { "get": { "tags": [ "Spend requests" ], "summary": "List spend requests and their decisions", "operationId": "listSpendIntents", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "schema": { "type": "string" } }, { "name": "recipientId", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "software", "cloud", "data", "professional_services", "travel", "marketing", "office", "other" ] } }, { "name": "commitmentType", "in": "query", "schema": { "type": "string", "enum": [ "PURCHASE_ORDER", "MERCHANT_ORDER", "API_USAGE", "SUBSCRIPTION", "INVOICE_PAYMENT", "DIRECT_PAYMENT" ] } }, { "name": "outcome", "in": "query", "schema": { "type": "string", "enum": [ "ALLOW", "REQUIRE_APPROVAL", "DENY" ] } } ], "responses": { "200": { "description": "A page of spend requests, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "hasMore", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SpendIntentRecord" } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Spend requests" ], "summary": "Ask what policy would decide", "description": "Submits a purchase an agent is considering and records what the policy would\nhave decided, together with the complete state that decision was based on.\n\nThis endpoint does not spend, authorize or reserve anything:\n- No mandate is created, and no field in the response points at one.\n- No approval is requested. `REQUIRE_APPROVAL` records that a person *would*\n have been asked; no one is asked.\n- The agent’s daily and monthly spend windows do not move.\n\nThe stored decision includes a snapshot of the limits, the spend window, the\nrecipient’s standing and the policy rules as they read at that instant, so the\nanswer remains explainable after the policy changes.", "operationId": "submitSpendIntent", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitSpendIntentRequest" } } } }, "responses": { "201": { "description": "The request was recorded and evaluated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendIntentResponse" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/spend-intents/{id}": { "get": { "tags": [ "Spend requests" ], "summary": "Get one spend request with its decision snapshot", "operationId": "getSpendIntent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request and what policy would have decided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendIntentRecord" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/mandates": { "get": { "tags": [ "Mandates" ], "summary": "List mandates", "operationId": "listMandates", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "DRAFT", "PROPOSED", "EVALUATING", "BLOCKED", "PENDING_APPROVAL", "APPROVED", "REJECTED", "EXECUTING", "COMPLETED", "FAILED", "REVOKED", "EXPIRED" ] } }, { "name": "agentId", "in": "query", "schema": { "type": "string" } }, { "name": "recipientId", "in": "query", "schema": { "type": "string" } }, { "name": "asset", "in": "query", "schema": { "type": "string", "enum": [ "EUR", "EURC", "USDC" ] } }, { "name": "requiresApproval", "in": "query", "schema": { "type": "boolean" } }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of mandates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "hasMore", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MandateListItem" } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Mandates" ], "summary": "Propose a payment", "description": "Creates a mandate and evaluates it against the agent’s policy in the same\nrequest. The response always contains the decision and the reasons behind it.\n\nThe resulting mandate is one of:\n- `APPROVED` — within policy, ready to execute.\n- `PENDING_APPROVAL` — a person must approve it first.\n- `BLOCKED` — the policy refused. This is terminal; propose a new mandate.\n\nProposing is never executing. No value moves until `/execute` is called.", "operationId": "proposeMandate", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeMandateRequest" } } } }, "responses": { "201": { "description": "The mandate was created and evaluated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeMandateResponse" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/mandates/{id}": { "get": { "tags": [ "Mandates" ], "summary": "Get a mandate with its full history", "operationId": "getMandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The mandate, its decision, approvals, attempts and audit trail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateDetail" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/mandates/{id}/approve": { "post": { "tags": [ "Mandates" ], "summary": "Approve a mandate", "description": "Requires the Approver, Admin or Owner role. When the organization requires a separate approver, the person who proposed the payment cannot approve it. Agents can never approve.", "operationId": "approveMandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "The mandate is approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/mandates/{id}/reject": { "post": { "tags": [ "Mandates" ], "summary": "Reject a mandate", "description": "Terminal. A rejected mandate can never be approved later.", "operationId": "rejectMandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "minLength": 3, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "The mandate is rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/mandates/{id}/revoke": { "post": { "tags": [ "Mandates" ], "summary": "Revoke a mandate", "description": "Withdraws authority before execution. Terminal, and not possible once a mandate has completed or while execution is in flight.", "operationId": "revokeMandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "The mandate is revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mandate" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/mandates/{id}/execute": { "post": { "tags": [ "Mandates" ], "summary": "Execute an approved mandate on the simulated rail", "description": "Executes exactly once. A repeat call, a retry after a timeout, or a second\ncaller racing the first cannot produce a second payment: the state machine, a\nrow lock, a database unique index and the rail’s own idempotency all refuse.\n\nRefused when the organization kill switch is active, when the mandate has\nexpired, and when the mandate is not approved.\n\nIn this release the rail is `mock-sandbox-rail`. It contacts nothing.", "operationId": "executeMandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "responses": { "200": { "description": "The execution completed or failed. Inspect `mandate.status`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "mandate", "attempt" ], "properties": { "mandate": { "$ref": "#/components/schemas/Mandate" }, "attempt": { "$ref": "#/components/schemas/PaymentAttempt" }, "reconciliationMatched": { "type": "boolean" } } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/audit-events": { "get": { "tags": [ "Audit" ], "summary": "List audit events", "operationId": "listAuditEvents", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "entityType", "in": "query", "schema": { "type": "string" } }, { "name": "entityId", "in": "query", "schema": { "type": "string" } }, { "name": "action", "in": "query", "schema": { "type": "string" } }, { "name": "actorType", "in": "query", "schema": { "type": "string", "enum": [ "USER", "AGENT", "SYSTEM" ] } } ], "responses": { "200": { "description": "A page of audit events.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "hasMore", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/organization": { "get": { "tags": [ "Organization" ], "summary": "Get organization settings and execution state", "operationId": "getOrganization", "responses": { "200": { "description": "The organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/organization/kill-switch": { "post": { "tags": [ "Organization" ], "summary": "Enable or disable execution organization-wide", "description": "Requires Owner or Admin. Disabling stops every new execution immediately. It does not revoke or reject anything: approvals stay valid and resume when the switch is turned back on, minus anything that expired meanwhile.", "operationId": "setKillSwitch", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "description": "Retry-safe key. Repeating a request with the same key returns the original result instead of performing the operation again. Reusing a key with a different body is a 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "executionEnabled" ], "properties": { "executionEnabled": { "type": "boolean" }, "reason": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "The execution state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/whoami": { "get": { "tags": [ "Organization" ], "summary": "The current principal, its role and its permissions", "operationId": "whoAmI", "responses": { "200": { "description": "The caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmI" } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No identity was resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller’s role does not permit this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Returned identically for a resource that does not exist and one that belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with current state — an invalid mandate transition, a reused idempotency key, or the execution kill switch being active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The spending policy denied the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/health": { "get": { "tags": [ "Organization" ], "summary": "Liveness and environment", "operationId": "health", "security": [], "responses": { "200": { "description": "Service status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "environment": { "type": "string", "enum": [ "sandbox" ] }, "version": { "type": "string" } } } } } } } } } }, "components": { "securitySchemes": { "localDevelopmentIdentity": { "type": "apiKey", "in": "header", "name": "X-Paygente-User", "description": "This sandbox has no authentication. The header names one of the seeded demo users (`maya`, `jonas`, `elena`, `viktor`) and the server resolves their role. It is a development shim, not a credential, and it is not a security control. An enterprise identity provider replaces it at this seam without any change to the authorization rules." } }, "schemas": { "Money": { "type": "object", "required": [ "asset", "amountMinor", "amount", "amountDisplay" ], "properties": { "asset": { "type": "string", "enum": [ "EUR", "EURC", "USDC" ] }, "amountMinor": { "type": "string", "pattern": "^\\d+$", "description": "Integer minor units as a string. The authoritative value. Parse as a big integer — never as a floating-point number.", "examples": [ "40000000" ] }, "amount": { "type": "string", "description": "Exact decimal.", "examples": [ "40.000000" ] }, "amountDisplay": { "type": "string", "examples": [ "€40.00 EURC" ] } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "string", "enum": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "conflict", "invalid_state_transition", "idempotency_key_reused", "policy_denied", "execution_disabled", "rate_limited", "rail_failure", "internal_error" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "code", "message" ], "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "correlationId": { "type": "string" } } } } }, "Agent": { "type": "object", "required": [ "id", "name", "externalId", "status" ], "properties": { "id": { "type": "string", "examples": [ "agt_01JQ8F7Z9K3M4N5P6Q7R8S9T0V" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "externalId": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DISABLED" ] }, "defaultPolicyId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AgentSummary": { "allOf": [ { "$ref": "#/components/schemas/Agent" }, { "type": "object", "properties": { "totalSimulatedSpend": { "$ref": "#/components/schemas/Money" }, "mandateCount": { "type": "integer" }, "lastActivityAt": { "type": [ "string", "null" ], "format": "date-time" } } } ] }, "CreateAgentRequest": { "type": "object", "required": [ "name", "externalId" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "description": { "type": "string", "maxLength": 1000 }, "externalId": { "type": "string", "pattern": "^[A-Za-z0-9._:-]+$" }, "defaultPolicyId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DISABLED" ], "default": "ACTIVE" } } }, "Recipient": { "type": "object", "required": [ "id", "displayName", "paymentIdentifier", "verificationStatus", "riskLevel" ], "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "type": { "type": "string" }, "paymentIdentifier": { "type": "string", "description": "A mock destination handle in the sandbox. Never a wallet address, IBAN, card number or any other payment credential." }, "verificationStatus": { "type": "string", "enum": [ "UNVERIFIED", "PENDING", "VERIFIED", "REJECTED" ] }, "riskLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "supportedAssets": { "type": "array", "items": { "type": "string", "enum": [ "EUR", "EURC", "USDC" ] } }, "isActive": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateRecipientRequest": { "type": "object", "required": [ "displayName", "type", "paymentIdentifier", "supportedAssets" ], "properties": { "displayName": { "type": "string", "minLength": 2, "maxLength": 160 }, "type": { "type": "string", "enum": [ "API_PROVIDER", "CLOUD_PROVIDER", "DATA_PROVIDER", "SAAS_VENDOR", "CONTRACTOR", "AGENT", "OTHER" ] }, "paymentIdentifier": { "type": "string", "pattern": "^[A-Za-z0-9._:-]+$" }, "verificationStatus": { "type": "string", "enum": [ "UNVERIFIED", "PENDING", "VERIFIED", "REJECTED" ], "default": "UNVERIFIED" }, "riskLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "default": "MEDIUM" }, "supportedAssets": { "type": "array", "items": { "type": "string", "enum": [ "EUR", "EURC", "USDC" ] } }, "isActive": { "type": "boolean", "default": true }, "notes": { "type": [ "string", "null" ] } } }, "PolicyRules": { "type": "object", "properties": { "maxTransactionAmount": { "$ref": "#/components/schemas/Money" }, "dailyLimit": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "monthlyLimit": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "approvalThreshold": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "allowedAssets": { "type": "array", "items": { "type": "string", "enum": [ "EUR", "EURC", "USDC" ] } }, "approvedRecipientIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Null means any recipient that satisfies the verification and risk rules." }, "maxMandateDurationSeconds": { "type": "integer" }, "allowFirstTimeRecipients": { "type": "boolean" }, "allowRecurringPayments": { "type": "boolean" }, "requireVerifiedRecipient": { "type": "boolean" }, "maxRecipientRiskLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "Policy": { "type": "object", "required": [ "id", "name", "rules", "isActive" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "rules": { "$ref": "#/components/schemas/PolicyRules" }, "isActive": { "type": "boolean" }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreatePolicyRequest": { "type": "object", "required": [ "name", "rules" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "description": { "type": "string", "maxLength": 1000 }, "isActive": { "type": "boolean", "default": true }, "rules": { "type": "object", "required": [ "maxTransactionAmount", "allowedAssets", "maxMandateDurationSeconds", "allowFirstTimeRecipients", "allowRecurringPayments", "requireVerifiedRecipient", "maxRecipientRiskLevel" ], "properties": { "maxTransactionAmount": { "type": "string", "examples": [ "100" ] }, "dailyLimit": { "type": [ "string", "null" ], "examples": [ "250" ] }, "monthlyLimit": { "type": [ "string", "null" ], "examples": [ "2000" ] }, "approvalThreshold": { "type": [ "string", "null" ], "examples": [ "40" ] }, "allowedAssets": { "type": "array", "items": { "type": "string", "enum": [ "EUR", "EURC", "USDC" ] } }, "approvedRecipientIds": { "type": [ "array", "null" ], "items": { "type": "string" } }, "maxMandateDurationSeconds": { "type": "integer", "minimum": 60 }, "allowFirstTimeRecipients": { "type": "boolean" }, "allowRecurringPayments": { "type": "boolean" }, "requireVerifiedRecipient": { "type": "boolean" }, "maxRecipientRiskLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } } } }, "SpendIntent": { "type": "object", "description": "A purchase an agent asked about. Recorded, never executed. There is no field linking a spend request to a mandate, and no column in which one could be stored.", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "SHADOW" ] }, "agentId": { "type": "string" }, "recipientId": { "type": "string" }, "money": { "$ref": "#/components/schemas/Money" }, "category": { "type": "string", "enum": [ "software", "cloud", "data", "professional_services", "travel", "marketing", "office", "other" ] }, "categoryLabel": { "type": "string" }, "commitmentType": { "type": "string", "enum": [ "PURCHASE_ORDER", "MERCHANT_ORDER", "API_USAGE", "SUBSCRIPTION", "INVOICE_PAYMENT", "DIRECT_PAYMENT" ], "nullable": true, "description": "What the business is committing to. Null only on requests recorded before commitment types existed; every new request carries one." }, "commitmentTypeLabel": { "type": "string", "nullable": true }, "purpose": { "type": "string" }, "projectReference": { "type": "string", "nullable": true }, "isRecurring": { "type": "boolean" }, "requestedExpiresAt": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "agent_api", "sandbox_simulator", "seed" ] }, "correlationId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "observedOnly": { "type": "boolean", "enum": [ true ], "description": "Always true. Shadow Mode observes; it never moves money." } } }, "SpendIntentDecision": { "type": "object", "description": "What policy would have decided, and everything it decided against.", "properties": { "id": { "type": "string" }, "outcome": { "type": "string", "enum": [ "ALLOW", "REQUIRE_APPROVAL", "DENY" ] }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "explanation": { "type": "string" }, "appliedPolicyId": { "type": "string", "nullable": true }, "engineVersion": { "type": "string" }, "evaluatedAt": { "type": "string", "format": "date-time" }, "snapshot": { "type": "object", "additionalProperties": true, "description": "The limits, spend window, recipient standing and policy rules as they read at evaluation time. Kept so the decision stays explainable after the policy changes. Evidence to read, not a structure to program against." } } }, "SpendIntentRecord": { "type": "object", "properties": { "intent": { "$ref": "#/components/schemas/SpendIntent" }, "decision": { "$ref": "#/components/schemas/SpendIntentDecision" } } }, "SpendIntentResponse": { "type": "object", "properties": { "intent": { "$ref": "#/components/schemas/SpendIntent" }, "decision": { "$ref": "#/components/schemas/SpendIntentDecision" }, "url": { "type": "string", "description": "Where a person can read this decision." } } }, "SubmitSpendIntentRequest": { "type": "object", "required": [ "agentId", "recipientId", "asset", "amount", "category", "commitmentType", "purpose" ], "properties": { "agentId": { "type": "string" }, "recipientId": { "type": "string" }, "asset": { "type": "string", "enum": [ "EUR", "EURC", "USDC" ] }, "amount": { "type": "string", "description": "Exact decimal string, e.g. \"40.50\". Never a JSON number.", "example": "40.50" }, "category": { "type": "string", "enum": [ "software", "cloud", "data", "professional_services", "travel", "marketing", "office", "other" ] }, "commitmentType": { "type": "string", "enum": [ "PURCHASE_ORDER", "MERCHANT_ORDER", "API_USAGE", "SUBSCRIPTION", "INVOICE_PAYMENT", "DIRECT_PAYMENT" ], "description": "Required, with no default. A default would be a guess recorded as a fact." }, "purpose": { "type": "string", "maxLength": 500 }, "projectReference": { "type": "string", "nullable": true, "maxLength": 64, "description": "Cost centre, ticket or project code. A policy may require one." }, "expiresAt": { "type": "string", "format": "date-time" }, "isRecurring": { "type": "boolean", "default": false } } }, "Mandate": { "type": "object", "required": [ "id", "status", "money", "purpose", "expiresAt", "simulated" ], "properties": { "id": { "type": "string", "examples": [ "mnd_01JQ8F7Z9K3M4N5P6Q7R8S9T0V" ] }, "status": { "type": "string", "enum": [ "DRAFT", "PROPOSED", "EVALUATING", "BLOCKED", "PENDING_APPROVAL", "APPROVED", "REJECTED", "EXECUTING", "COMPLETED", "FAILED", "REVOKED", "EXPIRED" ] }, "statusLabel": { "type": "string", "examples": [ "Waiting for approval" ] }, "agentId": { "type": "string" }, "recipientId": { "type": "string" }, "policyId": { "type": [ "string", "null" ] }, "money": { "$ref": "#/components/schemas/Money" }, "purpose": { "type": "string" }, "externalReference": { "type": [ "string", "null" ] }, "evidence": { "type": [ "string", "null" ] }, "requiresApproval": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revocationReason": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "correlationId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "simulated": { "const": true, "description": "No real payment occurred. This release has no live rail." } } }, "MandateListItem": { "allOf": [ { "$ref": "#/components/schemas/Mandate" }, { "type": "object", "properties": { "agentName": { "type": "string" }, "recipientName": { "type": "string" }, "recipientVerificationStatus": { "type": "string" } } } ] }, "ProposeMandateRequest": { "type": "object", "required": [ "agentId", "recipientId", "asset", "amount", "purpose" ], "properties": { "agentId": { "type": "string" }, "recipientId": { "type": "string" }, "asset": { "type": "string", "enum": [ "EUR", "EURC", "USDC" ] }, "amount": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,6})?$", "description": "Exact decimal string. Not a JSON number.", "examples": [ "40.50" ] }, "purpose": { "type": "string", "minLength": 5, "maxLength": 500 }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional. Defaults to the maximum duration the applied policy permits — never longer." }, "externalReference": { "type": [ "string", "null" ], "maxLength": 128 }, "evidence": { "type": [ "string", "null" ], "maxLength": 2000 }, "isRecurring": { "type": "boolean", "default": false } } }, "PolicyDecision": { "type": "object", "required": [ "outcome", "reasons", "engineVersion" ], "properties": { "outcome": { "type": "string", "enum": [ "ALLOW", "REQUIRE_APPROVAL", "DENY" ] }, "reasons": { "type": "array", "description": "Every reason that contributed, not only the first.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "appliedPolicyId": { "type": [ "string", "null" ] }, "engineVersion": { "type": "string", "examples": [ "policy-engine@1.0.0" ] }, "explanation": { "type": "string" } } }, "ProposeMandateResponse": { "type": "object", "required": [ "mandate", "decision", "url" ], "properties": { "mandate": { "$ref": "#/components/schemas/Mandate" }, "decision": { "$ref": "#/components/schemas/PolicyDecision" }, "url": { "type": "string", "format": "uri" } } }, "PaymentAttempt": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "REVERSED" ] }, "railName": { "type": "string", "examples": [ "mock-sandbox-rail" ] }, "externalId": { "type": [ "string", "null" ], "examples": [ "sim_4f2a91c0" ] }, "money": { "$ref": "#/components/schemas/Money" }, "failureReason": { "type": [ "string", "null" ] }, "failureMessage": { "type": [ "string", "null" ] }, "attemptNumber": { "type": "integer" }, "reconciliationMatched": { "type": [ "boolean", "null" ], "description": "Whether the rail moved exactly the authorised amount to exactly the authorised recipient." }, "startedAt": { "type": "string", "format": "date-time" }, "settledAt": { "type": [ "string", "null" ], "format": "date-time" }, "simulated": { "const": true } } }, "Approval": { "type": "object", "properties": { "id": { "type": "string" }, "decision": { "type": "string", "enum": [ "APPROVED", "REJECTED" ] }, "decidedByUserId": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "examples": [ "mandate.approved" ] }, "actorType": { "type": "string", "enum": [ "USER", "AGENT", "SYSTEM" ] }, "actorId": { "type": [ "string", "null" ] }, "actorLabel": { "type": "string" }, "entityType": { "type": "string" }, "entityId": { "type": "string" }, "previousStatus": { "type": [ "string", "null" ] }, "newStatus": { "type": [ "string", "null" ] }, "correlationId": { "type": "string" }, "metadata": { "type": "object", "description": "Sanitised context. Never contains secrets, credentials or raw request bodies.", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "MandateDetail": { "type": "object", "properties": { "mandate": { "$ref": "#/components/schemas/Mandate" }, "agent": { "$ref": "#/components/schemas/Agent" }, "recipient": { "$ref": "#/components/schemas/Recipient" }, "policy": { "oneOf": [ { "$ref": "#/components/schemas/Policy" }, { "type": "null" } ] }, "decision": { "oneOf": [ { "$ref": "#/components/schemas/PolicyDecision" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" } }, "paymentAttempts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentAttempt" } }, "auditEvents": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } } }, "Organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "country": { "type": "string" }, "environment": { "const": "sandbox" }, "defaultAsset": { "type": "string", "enum": [ "EUR", "EURC", "USDC" ] }, "defaultApprovalThreshold": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "requireSeparateApprover": { "type": "boolean" }, "executionEnabled": { "type": "boolean", "description": "False while the kill switch is active. No mandate can execute." }, "executionDisabledReason": { "type": [ "string", "null" ] }, "executionDisabledAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "WhoAmI": { "type": "object", "properties": { "userId": { "type": "string" }, "displayName": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "APPROVER", "OPERATOR", "VIEWER" ] }, "organization": { "$ref": "#/components/schemas/Organization" }, "permissions": { "type": "array", "items": { "type": "string" } }, "developmentIdentity": { "type": "boolean" } } } } } }