{ "openapi": "3.1.0", "info": { "title": "DeAlgo restricted commerce agent API", "version": "0.5.0", "description": "Proposal authority and agent-reported evidence. No general payment execution. Restricted commerce keys cannot call administrator or separate refund-only endpoints. JSON bodies limited to 8192 bytes. Exact integer currency minor units. No secrets or cardholder data." }, "servers": [ { "url": "https://dealgo-portal.vercel.app" } ], "security": [ { "AgentConnection": [] } ], "paths": { "/api/v1/commerce/payments": { "get": { "operationId": "listRecordedPayments", "summary": "Discover this agent’s recorded Stripe payments", "description": "Read-only stored receipt snapshots, never current refund eligibility or execution authority. Both receipt and decision must belong to the bound workspace and the decision to the bound agent. Administrator sessions can read workspace records; ordinary members cannot. Exact search covers all matching records, with pages of up to 50. Conflicting payment IDs are marked AMBIGUOUS and their target/amount fields are withheld. No raw outcomes, client secrets, customer data or provider calls.", "parameters": [ { "name": "q", "in": "query", "description": "Optional exact payment or decision ID.", "schema": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]*$" } }, { "name": "cursor", "in": "query", "description": "Opaque nextCursor from the previous response, bound to this workspace, agent and search.", "schema": { "type": "string", "maxLength": 1600 } } ], "responses": { "200": { "description": "Recorded snapshot. Readiness flags describe configuration only; execution still checks original authorization, owner-approved authority, provider state and refundable balance.", "content": { "application/json": { "schema": { "type": "object", "required": [ "scope", "workspaceId", "agentId", "interpretation", "readiness", "data", "nextCursor" ], "properties": { "scope": { "enum": [ "bound_agent", "workspace_administrator" ] }, "workspaceId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "interpretation": { "const": "RECORDED_SNAPSHOT_NOT_REFUND_ELIGIBILITY" }, "readiness": { "type": "object", "required": [ "intakePaused", "testProviderConfigured", "testRefundRuntimeAllowed", "liveExecutionEnabled" ], "properties": { "intakePaused": { "type": "boolean" }, "testProviderConfigured": { "type": "boolean" }, "testRefundRuntimeAllowed": { "type": "boolean" }, "liveExecutionEnabled": { "const": false } } }, "data": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "decisionId", "agentId", "paymentIntentId", "counterpartyId", "originalAmountMinor", "currency", "recordedProviderStatus", "recordedAt", "recordState" ], "properties": { "decisionId": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "paymentIntentId": { "type": [ "string", "null" ] }, "counterpartyId": { "type": [ "string", "null" ] }, "originalAmountMinor": { "type": [ "integer", "null" ], "minimum": 1 }, "currency": { "type": [ "string", "null" ] }, "recordedProviderStatus": { "enum": [ "succeeded", "processing", "requires_payment_method", "requires_confirmation", "requires_action", "requires_capture", "canceled", "unknown" ] }, "recordedAt": { "type": "string", "format": "date-time" }, "recordState": { "enum": [ "RECORDED", "INCOMPLETE", "AMBIGUOUS" ] } } } }, "nextCursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid search or cursor." }, "401": { "description": "Missing, invalid or revoked credential." }, "403": { "description": "Insufficient access." }, "409": { "description": "Displayed workspace changed." }, "429": { "description": "Rate limited." } } } }, "/api/v1/commerce/capabilities": { "get": { "operationId": "connectionStatus", "description": "Read bound identity, intake pause, active mandate count and evidence grant. Snapshot only, not future authority.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "schemaVersion", "connected", "agentId", "workspaceId", "executionEnabled", "canApprove" ], "properties": { "schemaVersion": { "const": "1" }, "connected": { "const": true }, "agentId": { "type": "string" }, "workspaceId": { "type": "string" }, "executionEnabled": { "const": false }, "canApprove": { "const": false }, "intakePaused": { "type": "boolean" }, "activeMandates": { "type": "integer" }, "evidence": { "type": "object" }, "nextSteps": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/commerce/mandates": { "get": { "operationId": "listMandates", "description": "Latest 100 mandates for this agent, including expired/revoked. Select the intended ID and check terms.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "mandates": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/commerce/onboarding/draft": { "post": { "operationId": "preparePolicy", "description": "Validate without saving or granting authority. agentId must match key. Use requestPolicy for a persisted owner review handoff.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "$ref": "#/components/schemas/PolicyDraft" }, "activated": { "const": false }, "requiresAdministratorReview": { "const": true }, "executionEnabled": { "const": false } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyDraft" } } } } } }, "/api/v1/commerce/proposals": { "get": { "operationId": "listProposals", "description": "Latest 100 proposals for this agent; retain IDs for later reads.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposals": { "type": "array", "items": { "type": "object" } }, "executionEnabled": { "const": false } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "proposeDeal", "description": "Reserve allowance and request human review. APPROVED never executes payment. Persist request key and preserve exact terms on retry.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": ["proposal", "executionEnabled"], "properties": { "proposal": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "enum": [ "PENDING", "APPROVED", "REJECTED", "CANCELLED" ] } } }, "executionEnabled": { "const": false } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalInput" } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,128}$" } } ] } }, "/api/v1/commerce/proposals/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-]{1,100}$" } } ], "get": { "operationId": "proposalStatus", "description": "Read one owned proposal. No resubmission or settlement.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": ["proposal", "executionEnabled"], "properties": { "proposal": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "enum": [ "PENDING", "APPROVED", "REJECTED", "CANCELLED" ] } } }, "executionEnabled": { "const": false } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/commerce/tool-evidence": { "post": { "operationId": "reportToolEvidence", "description": "Requires owner opt-in and an owned proposal. Reporting does not authorize running the tool. AGENT_REPORTED metadata only. Preserve eventKey and exact payload on retry.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEvidence" } } } } } }, "/api/v1/commerce/policy-requests": { "get": { "operationId": "listPolicyRequests", "description": "Oldest 50 unexpired pending requests for this agent. Retain IDs for later status reads.", "responses": { "200": { "description": "Pending requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "const": 50 }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyRequest" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "requestPolicy", "description": "Persist immutable terms for owner review, not authority. Agent binding and stable Idempotency-Key required. Expires within 24 hours. Limit 25 pending requests per agent. Same-key changed terms or connection returns 409. The owner alone can activate; this agent API has no approval endpoint.", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Saved or replayed request; no authority granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyRequest" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyDraft" } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,128}$" } } ] } }, "/api/v1/commerce/policy-requests/{id}": { "get": { "operationId": "policyRequestStatus", "description": "Read owned request history; ACTIVATED is not a current mandate validity check or execution permission.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-]{1,100}$" } } ], "responses": { "200": { "description": "Stored request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyRequest" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting terms or state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure; mutation outcome may be unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/commerce/proposals/{id}/refund": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } } ], "post": { "operationId": "stageTestRefund", "description": "Prepare one exact test refund from an approved proposal. Never executes money. Retry same proposal and digest to return the existing operation. Separate owner session submits and reconciles. Never create a replacement after uncertainty.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["digest"], "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "canExecute=false; execution contains refundRequestId; refund contains recorded status and evidence; reviewPath opens owner refund operations." }, "409": { "description": "Missing approval, stale authority, mismatched terms or intake paused." }, "403": { "description": "Revoked connection or agent mismatch." }, "422": { "description": "Original decision not eligible for a refund." } } }, "get": { "operationId": "testRefundStatus", "description": "Read the owned linked test refund, release start and stored evidence. No provider request or resubmission.", "responses": { "200": { "description": "execution and refund, or null if not staged; mode=test and canExecute=false." }, "404": { "description": "Proposal not in connection scope." } } } } }, "components": { "securitySchemes": { "AgentConnection": { "type": "http", "scheme": "bearer", "description": "Administrator-issued commerce key, bound to one workspace and agent." } }, "schemas": { "PolicyDraft": { "type": "object", "additionalProperties": false, "properties": { "agentId": { "type": "string", "minLength": 1, "maxLength": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "currency": { "type": "string", "pattern": "^[a-z]{3}$" }, "actions": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "enum": ["purchase", "sale", "refund", "payout", "subscription"] } }, "counterparties": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "maxSingleMinor": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "budgetMinor": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "expiresAt": { "type": "string", "format": "date-time", "description": "Future, at most 90 days. maxSingleMinor must not exceed budgetMinor." } }, "required": [ "agentId", "name", "currency", "actions", "counterparties", "maxSingleMinor", "budgetMinor", "expiresAt" ] }, "ProposalInput": { "type": "object", "additionalProperties": false, "properties": { "mandateId": { "type": "string", "minLength": 1, "maxLength": 100 }, "action": { "type": "string", "enum": ["purchase", "sale", "refund", "payout", "subscription"] }, "counterpartyId": { "type": "string", "minLength": 1, "maxLength": 100 }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "currency": { "type": "string", "pattern": "^[a-z]{3}$" }, "description": { "type": "string", "minLength": 1, "maxLength": 1000 }, "refundTarget": { "$ref": "#/components/schemas/RefundTarget" } }, "required": [ "mandateId", "action", "counterpartyId", "amountMinor", "currency", "description" ] }, "ToolEvidence": { "type": "object", "additionalProperties": false, "properties": { "eventKey": { "type": "string", "minLength": 1, "maxLength": 128 }, "proposalId": { "type": "string", "minLength": 1, "maxLength": 128 }, "tool": { "type": "string", "minLength": 1, "maxLength": 80 }, "outcome": { "type": "string", "enum": ["succeeded", "failed"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time" }, "inputSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "outputSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "evidenceUrl": { "type": "string", "format": "uri", "maxLength": 500, "description": "Allowed HTTPS origin, no credentials, query or fragment. Stored reference only." }, "parentEventId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "eventKey", "proposalId", "tool", "outcome", "startedAt", "finishedAt", "inputSha256", "outputSha256" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" } }, "required": ["code"] } }, "required": ["error"] }, "PolicyRequest": { "type": "object", "required": [ "id", "workspaceId", "agentId", "digest", "terms", "status", "expiresAt", "executionEnabled" ], "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "agentId": { "type": "string" }, "connectionId": { "type": "string" }, "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "terms": { "$ref": "#/components/schemas/PolicyDraft" }, "status": { "enum": ["PENDING", "ACTIVATED", "REJECTED"] }, "expiresAt": { "type": "string", "format": "date-time" }, "expired": { "type": "boolean" }, "mandateId": { "type": ["string", "null"] }, "reviewPath": { "type": "string", "description": "Same-origin owner review path. Owner signs in and selects the indicated workspace." }, "executionEnabled": { "const": false } } }, "RefundTarget": { "type": "object", "additionalProperties": false, "required": ["decisionId", "paymentIntentId"], "properties": { "decisionId": { "type": "string", "maxLength": 100 }, "paymentIntentId": { "type": "string", "pattern": "^pi_[a-zA-Z0-9_]+$" }, "reason": { "type": ["string", "null"], "enum": ["duplicate", "fraudulent", "requested_by_customer", null] } }, "description": "Refund proposals only. counterpartyId must equal stripe:test:. Original decision must belong to the same agent and workspace. Target is included in the proposal digest." } } } }