{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentGuard API",
    "version": "0.1.0",
    "license": {
      "name": "Apache-2.0",
      "identifier": "Apache-2.0"
    },
    "description": "Financial authorization gateway for AI agents paying through PayPal. Errors are `{\"error\": string}`. Responses are JSON with `cache-control: no-store`. Docs: https://agentguard-orcin.vercel.app/docs"
  },
  "servers": [
    {
      "url": "https://agentguard-orcin.vercel.app",
      "description": "Hosted demo (PayPal sandbox)"
    },
    {
      "url": "http://localhost:8787",
      "description": "Local"
    }
  ],
  "tags": [
    {
      "name": "Meta",
      "description": "Health and liveness"
    },
    {
      "name": "Jobs",
      "description": "Scheduled jobs (Bearer CRON_SECRET)"
    },
    {
      "name": "Keys",
      "description": "Issuer signing keys: publish, rotate, mark compromised"
    },
    {
      "name": "Receipts",
      "description": "Signed Proof-of-Intent receipts for captured payments"
    },
    {
      "name": "Setup",
      "description": "Agents and PayPal wallet vaulting"
    },
    {
      "name": "Mandates",
      "description": "Spending mandates the user signs with a passkey"
    },
    {
      "name": "Passkeys",
      "description": "Passkey enrollment, re-enrollment and time-locked recovery"
    },
    {
      "name": "Approvals",
      "description": "Payments held for the user's passkey approval"
    },
    {
      "name": "Agent",
      "description": "Calls an agent makes with its own key: product search, payments, receipts"
    },
    {
      "name": "Catalog",
      "description": "Channel3 product search for the owner"
    },
    {
      "name": "Payments",
      "description": "Payment log and crash recovery"
    },
    {
      "name": "Control",
      "description": "Operator kill-switch"
    },
    {
      "name": "Audit",
      "description": "Hash-chained audit ledger, attestations and anchors"
    }
  ],
  "components": {
    "securitySchemes": {
      "admin": {
        "type": "http",
        "scheme": "bearer",
        "description": "AGENTGUARD_ADMIN_TOKEN (owner/operator)"
      },
      "agent": {
        "type": "http",
        "scheme": "bearer",
        "description": "Per-agent API key from POST /v1/agents"
      },
      "cron": {
        "type": "http",
        "scheme": "bearer",
        "description": "CRON_SECRET"
      }
    },
    "schemas": {
      "MandateConstraints": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "description": "ISO 4217",
            "example": "USD"
          },
          "max_total": {
            "type": "string",
            "example": "25.00"
          },
          "max_per_transaction": {
            "type": "string"
          },
          "max_transactions": {
            "type": "integer"
          },
          "allowed_categories": {
            "type": "array",
            "items": {
              "enum": [
                "PHYSICAL_GOODS",
                "DIGITAL_GOODS",
                "DONATION",
                "UNSPECIFIED"
              ]
            }
          },
          "payee_allowlist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "payee_blocklist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "max_quantity_per_item": {
            "type": "integer"
          },
          "require_human_approval_over": {
            "type": "string"
          },
          "require_merchant_order": {
            "type": "boolean"
          },
          "sku_allowlist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "currency",
          "max_total",
          "max_transactions"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Every non-2xx response",
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong",
            "example": "unauthorized"
          }
        },
        "required": [
          "error"
        ]
      },
      "Health": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "stuck": {
            "type": "integer",
            "description": "Payments stuck in reserved/authorized for over a minute"
          },
          "last_recovery": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Last reconciliation run"
          }
        },
        "required": [
          "ok",
          "stuck"
        ]
      },
      "AgentCredentials": {
        "type": "object",
        "properties": {
          "agent_id": {
            "type": "string"
          },
          "api_key": {
            "type": "string",
            "description": "Shown once; store it as the agent's secret"
          }
        },
        "required": [
          "agent_id",
          "api_key"
        ]
      },
      "Check": {
        "type": "object",
        "properties": {
          "check": {
            "type": "string",
            "example": "per_transaction_limit"
          },
          "pass": {
            "type": "boolean"
          },
          "detail": {
            "type": "string"
          }
        },
        "required": [
          "check",
          "pass",
          "detail"
        ]
      },
      "RiskSignal": {
        "type": "object",
        "properties": {
          "signal": {
            "type": "string",
            "example": "catalog_price_above_market"
          },
          "severity": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "detail": {
            "type": "string"
          }
        },
        "required": [
          "signal",
          "severity",
          "detail"
        ]
      },
      "Evaluation": {
        "type": "object",
        "properties": {
          "decision": {
            "type": "string",
            "enum": [
              "approve",
              "reject",
              "needs_human"
            ]
          },
          "proposal_hash": {
            "type": "string",
            "description": "sha256 of the canonical proposal"
          },
          "amount_minor": {
            "type": "integer",
            "description": "Amount in minor units, from the PayPal order"
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Check"
            }
          },
          "risk": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RiskSignal"
            }
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "decision",
          "proposal_hash",
          "amount_minor",
          "checks",
          "risk",
          "reasons"
        ]
      },
      "PaymentDecision": {
        "type": "object",
        "properties": {
          "payment_id": {
            "type": "string",
            "example": "pay_…"
          },
          "decision": {
            "type": "string",
            "enum": [
              "approve",
              "reject",
              "needs_human"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "rejected",
              "needs_human",
              "reserved",
              "authorized",
              "captured",
              "voided",
              "failed"
            ]
          },
          "evaluation": {
            "$ref": "#/components/schemas/Evaluation"
          },
          "approval_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Set when the payment waits for the user's passkey approval"
          },
          "paypal": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "authorization_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "capture_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "payment_id",
          "decision",
          "status",
          "evaluation"
        ]
      },
      "Spend": {
        "type": "object",
        "properties": {
          "spent_minor": {
            "type": "integer"
          },
          "reserved_minor": {
            "type": "integer"
          },
          "tx_count": {
            "type": "integer"
          }
        }
      },
      "Mandate": {
        "type": "object",
        "properties": {
          "mandate_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "agent_id": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "constraints": {
            "$ref": "#/components/schemas/MandateConstraints"
          },
          "created_at": {
            "type": "string"
          },
          "expires_at": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          }
        },
        "required": [
          "mandate_id",
          "user_id",
          "agent_id",
          "purpose",
          "constraints",
          "created_at",
          "expires_at"
        ]
      },
      "AgentMandate": {
        "type": "object",
        "properties": {
          "mandate": {
            "$ref": "#/components/schemas/Mandate"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "unsigned",
              "active",
              "frozen",
              "revoked",
              "exhausted",
              "expired"
            ]
          },
          "spend": {
            "$ref": "#/components/schemas/Spend"
          }
        },
        "required": [
          "mandate",
          "status"
        ]
      },
      "CatalogOffer": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "example": "bestbuy.com"
          },
          "url": {
            "type": "string",
            "description": "Retailer buy link"
          },
          "price": {
            "type": "string",
            "example": "39.00"
          },
          "price_minor": {
            "type": "integer"
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "availability": {
            "type": "string",
            "example": "InStock"
          },
          "condition": {
            "type": [
              "string",
              "null"
            ],
            "description": "new, used, refurbished; null when unknown"
          }
        },
        "required": [
          "domain",
          "price",
          "currency"
        ]
      },
      "CatalogProduct": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string",
            "description": "Use as the PayPal order item sku",
            "example": "channel3:2yh8WH5"
          },
          "channel3_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "image": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogOffer"
            }
          },
          "best_offer": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CatalogOffer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cheapest in-stock offer within the mandate's currency and ceiling"
          },
          "mandate_fit": {
            "type": "object",
            "properties": {
              "fits": {
                "type": "boolean"
              },
              "needs_approval": {
                "type": "boolean"
              },
              "checks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Check"
                }
              }
            }
          }
        },
        "required": [
          "product_id",
          "title",
          "offers"
        ]
      },
      "ProductSearchResult": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "string",
            "example": "channel3"
          },
          "mandate_id": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "max_price": {
            "type": "string",
            "description": "Price ceiling applied: min(per-payment cap, remaining budget)"
          },
          "currency": {
            "type": "string"
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogProduct"
            }
          },
          "next_page_token": {
            "type": [
              "string",
              "null"
            ]
          },
          "how_to_pay": {
            "type": "string"
          }
        },
        "required": [
          "provider",
          "products",
          "max_price",
          "currency"
        ]
      },
      "ReceiptEnvelope": {
        "type": "object",
        "properties": {
          "receipt": {
            "type": "object",
            "additionalProperties": true,
            "description": "agentguard.proof-of-intent/v1 receipt: mandate + passkey signature, PayPal order snapshot, decision, capture"
          },
          "signature": {
            "type": "object",
            "properties": {
              "alg": {
                "type": "string",
                "example": "Ed25519"
              },
              "kid": {
                "type": "string"
              },
              "key_id": {
                "type": "string"
              },
              "public_key_pem": {
                "type": "string"
              },
              "value": {
                "type": "string"
              }
            },
            "required": [
              "alg",
              "value"
            ]
          },
          "timestamps": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true,
              "description": "RFC 3161 timestamp token"
            }
          },
          "anchor": {
            "type": "object",
            "additionalProperties": true,
            "description": "Merkle inclusion proof for the audit-chain anchor"
          }
        },
        "required": [
          "receipt",
          "signature"
        ]
      },
      "ReceiptSummary": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string"
          },
          "payment_id": {
            "type": "string"
          },
          "capture_id": {
            "type": "string"
          },
          "receipt_hash": {
            "type": "string"
          },
          "issued_at": {
            "type": "string"
          }
        },
        "required": [
          "receipt_id",
          "payment_id"
        ]
      },
      "IssuerKey": {
        "type": "object",
        "properties": {
          "kid": {
            "type": "string"
          },
          "kty": {
            "type": "string",
            "example": "OKP"
          },
          "crv": {
            "type": "string",
            "example": "Ed25519"
          },
          "x": {
            "type": "string"
          },
          "public_key_pem": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created": {
            "type": "string"
          },
          "retired": {
            "type": [
              "string",
              "null"
            ]
          },
          "compromised_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "kid"
        ]
      },
      "IssuerKeySet": {
        "type": "object",
        "properties": {
          "issuer": {
            "type": "string"
          },
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IssuerKey"
            }
          }
        },
        "required": [
          "keys"
        ]
      },
      "AuditEntry": {
        "type": "object",
        "properties": {
          "seq": {
            "type": "integer"
          },
          "ts": {
            "type": "string"
          },
          "event": {
            "type": "string",
            "example": "payment.captured"
          },
          "ref": {
            "type": [
              "string",
              "null"
            ]
          },
          "payload": {
            "type": "object",
            "additionalProperties": true
          },
          "prev_hash": {
            "type": "string"
          },
          "hash": {
            "type": "string",
            "description": "sha256(prev_hash|ts|event|ref|canonical(payload))"
          }
        },
        "required": [
          "seq",
          "ts",
          "event",
          "prev_hash",
          "hash"
        ]
      },
      "AuditVerification": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "length": {
            "type": "integer"
          },
          "brokenAt": {
            "type": "integer",
            "description": "First entry whose hash or link does not verify"
          }
        },
        "required": [
          "ok",
          "length"
        ]
      },
      "PauseState": {
        "type": "object",
        "properties": {
          "paused": {
            "type": "boolean"
          },
          "reason": {
            "type": "string"
          },
          "by": {
            "type": "string"
          },
          "since": {
            "type": "string"
          }
        },
        "required": [
          "paused"
        ]
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "description": "Health: ok, stuck payment count, last recovery run",
        "tags": [
          "Meta"
        ],
        "summary": "Health check",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "operationId": "getLiveness",
        "description": "Liveness probe (plain 200)",
        "tags": [
          "Meta"
        ],
        "summary": "Get liveness",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "headLiveness",
        "description": "Liveness probe, no body",
        "tags": [
          "Meta"
        ],
        "summary": "Head liveness",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cron/anchor": {
      "get": {
        "operationId": "runAnchorJob",
        "description": "Timestamp pending receipts and anchor the audit head (Bearer CRON_SECRET)",
        "tags": [
          "Jobs"
        ],
        "summary": "Run anchor job",
        "security": [
          {
            "cron": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "runAnchorJobPost",
        "description": "Same as GET, for pg_net callers",
        "tags": [
          "Jobs"
        ],
        "summary": "Run anchor job post",
        "security": [
          {
            "cron": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cron/maintenance": {
      "get": {
        "operationId": "runMaintenanceJob",
        "description": "Expire recovery locks, retry notifications, converge stuck payments",
        "tags": [
          "Jobs"
        ],
        "summary": "Run maintenance job",
        "security": [
          {
            "cron": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "runMaintenanceJobPost",
        "description": "Same as GET, for pg_net callers",
        "tags": [
          "Jobs"
        ],
        "summary": "Run maintenance job post",
        "security": [
          {
            "cron": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/agentguard-key": {
      "get": {
        "operationId": "getIssuerKey",
        "description": "Active issuer public key (legacy single-key form)",
        "tags": [
          "Keys"
        ],
        "summary": "Get issuer key",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/agentguard-keys": {
      "get": {
        "operationId": "getIssuerKeySet",
        "description": "Issuer key set: every key with kid, status, created_at, retired_at, compromised_at. Pin this.",
        "tags": [
          "Keys"
        ],
        "summary": "Get issuer key set",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssuerKeySet"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/receipts/{id}": {
      "get": {
        "operationId": "getPublicReceipt",
        "description": "Public receipt lookup (only when AGENTGUARD_PUBLIC_RECEIPTS=1)",
        "tags": [
          "Receipts"
        ],
        "summary": "Get public receipt",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents": {
      "post": {
        "operationId": "registerAgent",
        "description": "Register an agent and return its API key (shown once)",
        "tags": [
          "Setup"
        ],
        "summary": "Register agent",
        "security": [
          {
            "admin": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_id": {
                    "type": "string",
                    "description": "Owner user id",
                    "example": "demo-user"
                  },
                  "agent_id": {
                    "type": "string",
                    "description": "Agent id",
                    "example": "shopper"
                  }
                },
                "required": [
                  "user_id",
                  "agent_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentCredentials"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/setup": {
      "post": {
        "operationId": "startWalletSetup",
        "description": "Start PayPal wallet vaulting; returns the setup token with the buyer consent link",
        "tags": [
          "Setup"
        ],
        "summary": "Start wallet setup",
        "security": [
          {
            "admin": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "user_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/return": {
      "get": {
        "operationId": "completeWalletSetup",
        "description": "PayPal redirect target after buyer consent; links the vaulted wallet",
        "tags": [
          "Setup"
        ],
        "summary": "Complete wallet setup",
        "security": [],
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "description": "One-time state from /v1/wallets/setup",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "approval_token_id",
            "in": "query",
            "description": "PayPal setup token id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/link": {
      "post": {
        "operationId": "linkWallet",
        "description": "Link an existing PayPal vault id to a user",
        "tags": [
          "Setup"
        ],
        "summary": "Link wallet",
        "security": [
          {
            "admin": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_id": {
                    "type": "string"
                  },
                  "vault_id": {
                    "type": "string"
                  },
                  "payer_email": {
                    "type": "string"
                  }
                },
                "required": [
                  "user_id",
                  "vault_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mandates": {
      "post": {
        "operationId": "createMandate",
        "description": "Create a draft mandate from structured constraints",
        "tags": [
          "Mandates"
        ],
        "summary": "Create mandate",
        "security": [
          {
            "admin": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_id": {
                    "type": "string"
                  },
                  "agent_id": {
                    "type": "string"
                  },
                  "purpose": {
                    "type": "string"
                  },
                  "ttl_minutes": {
                    "type": "integer"
                  },
                  "constraints": {
                    "$ref": "#/components/schemas/MandateConstraints"
                  }
                },
                "required": [
                  "user_id",
                  "agent_id",
                  "purpose"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listMandates",
        "description": "List mandates with spend state and summary",
        "tags": [
          "Mandates"
        ],
        "summary": "List mandates",
        "security": [
          {
            "admin": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mandates/draft-from-text": {
      "post": {
        "operationId": "draftMandateFromText",
        "description": "Draft a mandate from plain English (model proposes, deterministic parser bounds it)",
        "tags": [
          "Mandates"
        ],
        "summary": "Draft mandate from text",
        "security": [
          {
            "admin": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_id": {
                    "type": "string"
                  },
                  "agent_id": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string",
                    "example": "Buy API credits from shop@example.com, at most $25 total, ask me above $5"
                  }
                },
                "required": [
                  "user_id",
                  "agent_id",
                  "text"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mandates/{id}": {
      "get": {
        "operationId": "getMandate",
        "description": "Mandate, status and spend",
        "tags": [
          "Mandates"
        ],
        "summary": "Get mandate",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mandates/{id}/sign-request": {
      "post": {
        "operationId": "getMandateSigningOptions",
        "description": "Get WebAuthn options whose challenge is the mandate hash",
        "tags": [
          "Mandates"
        ],
        "summary": "Get mandate signing options",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mandates/{id}/confirm": {
      "post": {
        "operationId": "confirmMandate",
        "description": "Activate a mandate with the user's passkey assertion",
        "tags": [
          "Mandates"
        ],
        "summary": "Confirm mandate",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mandate_hash": {
                    "type": "string"
                  },
                  "assertion": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "WebAuthn assertion (navigator.credentials.get response, JSON-encoded) over the challenge returned by the matching *-request call"
                  }
                },
                "required": [
                  "mandate_hash",
                  "assertion"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mandates/{id}/revoke-request": {
      "post": {
        "operationId": "getMandateRevocationOptions",
        "description": "Get WebAuthn options for revocation",
        "tags": [
          "Mandates"
        ],
        "summary": "Get mandate revocation options",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mandates/{id}/revoke": {
      "post": {
        "operationId": "revokeMandate",
        "description": "Revoke with the user's passkey (drafts can be discarded without one)",
        "tags": [
          "Mandates"
        ],
        "summary": "Revoke mandate",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "assertion": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "WebAuthn assertion (navigator.credentials.get response, JSON-encoded) over the challenge returned by the matching *-request call"
                  },
                  "reason": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{id}/passkey": {
      "get": {
        "operationId": "getUserPasskey",
        "description": "Whether the user has a passkey, and its credential id",
        "tags": [
          "Passkeys"
        ],
        "summary": "Get user passkey",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{id}/enrollments": {
      "post": {
        "operationId": "createEnrollmentLink",
        "description": "Issue a single-use enrollment link (15 min default)",
        "tags": [
          "Passkeys"
        ],
        "summary": "Create enrollment link",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "issued_by": {
                    "type": "string"
                  },
                  "ttl_minutes": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/enroll/options": {
      "post": {
        "operationId": "getEnrollmentOptions",
        "description": "Redeem step 1: registration options for an enrollment token",
        "tags": [
          "Passkeys"
        ],
        "summary": "Get passkey registration options",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/enroll": {
      "post": {
        "operationId": "enrollPasskey",
        "description": "Redeem step 2: register the passkey",
        "tags": [
          "Passkeys"
        ],
        "summary": "Register a passkey",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "response": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "navigator.credentials.create response"
                  }
                },
                "required": [
                  "token",
                  "response"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{id}/reenroll-request": {
      "post": {
        "operationId": "getReenrollmentOptions",
        "description": "Options for replacing a passkey with the current one",
        "tags": [
          "Passkeys"
        ],
        "summary": "Get reenrollment options",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{id}/reenroll": {
      "post": {
        "operationId": "reenrollPasskey",
        "description": "Mint a re-enrollment token authorized by the current passkey",
        "tags": [
          "Passkeys"
        ],
        "summary": "Reenroll passkey",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "assertion": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "WebAuthn assertion (navigator.credentials.get response, JSON-encoded) over the challenge returned by the matching *-request call"
                  }
                },
                "required": [
                  "assertion"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{id}/recovery": {
      "get": {
        "operationId": "getRecoveryState",
        "description": "Time-locked recovery state",
        "tags": [
          "Passkeys"
        ],
        "summary": "Get recovery state",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{id}/recovery/cancel-request": {
      "post": {
        "operationId": "getRecoveryCancelOptions",
        "description": "Options to cancel a recovery with the current passkey",
        "tags": [
          "Passkeys"
        ],
        "summary": "Get recovery cancel options",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{id}/recovery/cancel": {
      "post": {
        "operationId": "cancelRecovery",
        "description": "Cancel a pending recovery",
        "tags": [
          "Passkeys"
        ],
        "summary": "Cancel recovery",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "assertion": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "WebAuthn assertion (navigator.credentials.get response, JSON-encoded) over the challenge returned by the matching *-request call"
                  }
                },
                "required": [
                  "assertion"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/approvals": {
      "get": {
        "operationId": "listApprovals",
        "description": "Payments held for the owner",
        "tags": [
          "Approvals"
        ],
        "summary": "List approvals",
        "security": [
          {
            "admin": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/approvals/{id}/request": {
      "post": {
        "operationId": "getApprovalOptions",
        "description": "Approval statement and WebAuthn options (5-minute nonce)",
        "tags": [
          "Approvals"
        ],
        "summary": "Get approval options",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "approve": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "approve"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/approvals/{id}": {
      "post": {
        "operationId": "resolveApproval",
        "description": "Approve or deny with the user's passkey. The admin token alone is refused.",
        "tags": [
          "Approvals"
        ],
        "summary": "Resolve approval",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "approve": {
                    "type": "boolean"
                  },
                  "assertion": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "WebAuthn assertion (navigator.credentials.get response, JSON-encoded) over the challenge returned by the matching *-request call"
                  },
                  "approver": {
                    "type": "string"
                  }
                },
                "required": [
                  "approve",
                  "assertion"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agent/payments": {
      "post": {
        "operationId": "proposePayment",
        "description": "Propose a payment (30/min per agent; 429 above)",
        "tags": [
          "Agent"
        ],
        "summary": "Propose a payment",
        "security": [
          {
            "agent": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mandate_id": {
                    "type": "string"
                  },
                  "agent_id": {
                    "type": "string"
                  },
                  "idempotency_key": {
                    "type": "string"
                  },
                  "paypal_order_id": {
                    "type": "string",
                    "description": "Merchant-created AUTHORIZE order (preferred). Do not combine with payee/currency/items."
                  },
                  "payee": {
                    "type": "object",
                    "properties": {
                      "merchant_id": {
                        "type": "string"
                      },
                      "email_address": {
                        "type": "string"
                      },
                      "display_name": {
                        "type": "string"
                      }
                    },
                    "description": "Vaulted path only (untrusted)"
                  },
                  "currency": {
                    "type": "string",
                    "description": "Vaulted path only"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "LineItem: name, sku, category, quantity, unit_amount"
                    },
                    "description": "Vaulted path only (untrusted)"
                  },
                  "context": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "source_url": {
                          "type": "string"
                        },
                        "excerpt": {
                          "type": "string"
                        }
                      }
                    },
                    "description": "Untrusted context the agent saw; scored for injection, advisory only"
                  },
                  "agent_rationale": {
                    "type": "string"
                  }
                },
                "required": [
                  "mandate_id",
                  "agent_id",
                  "idempotency_key"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentDecision"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Paused by operator kill-switch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agent/products/search": {
      "post": {
        "operationId": "searchProducts",
        "description": "Search the Channel3 product catalog within the mandate's currency and remaining budget (discovery only; never pays)",
        "tags": [
          "Agent"
        ],
        "summary": "Search products",
        "security": [
          {
            "agent": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mandate_id": {
                    "type": "string"
                  },
                  "query": {
                    "type": "string",
                    "example": "65W USB-C charger"
                  },
                  "limit": {
                    "type": "integer",
                    "description": "1-30, default 8"
                  },
                  "page_token": {
                    "type": "string",
                    "description": "next_page_token from a previous search"
                  }
                },
                "required": [
                  "mandate_id",
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductSearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agent/payments/{id}": {
      "get": {
        "operationId": "getAgentPayment",
        "description": "Payment status (the calling agent's own only)",
        "tags": [
          "Agent"
        ],
        "summary": "Get agent payment",
        "security": [
          {
            "agent": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentDecision"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agent/payments/{id}/receipt": {
      "get": {
        "operationId": "getAgentPaymentReceipt",
        "description": "Proof-of-Intent receipt for a captured payment",
        "tags": [
          "Agent"
        ],
        "summary": "Get agent payment receipt",
        "security": [
          {
            "agent": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agent/mandates/{id}": {
      "get": {
        "operationId": "getAgentMandate",
        "description": "The agent's own mandate, status and spend",
        "tags": [
          "Agent"
        ],
        "summary": "Get agent mandate",
        "security": [
          {
            "agent": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentMandate"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/products/search": {
      "post": {
        "operationId": "searchProductsForMandate",
        "description": "Owner view of the same Channel3 search, with an advisory mandate-fit check per product",
        "tags": [
          "Catalog"
        ],
        "summary": "Search products for mandate",
        "security": [
          {
            "admin": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mandate_id": {
                    "type": "string"
                  },
                  "query": {
                    "type": "string",
                    "example": "laptop stand"
                  },
                  "limit": {
                    "type": "integer"
                  },
                  "page_token": {
                    "type": "string"
                  }
                },
                "required": [
                  "mandate_id",
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductSearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/products/status": {
      "get": {
        "operationId": "getProductSearchStatus",
        "description": "Whether Channel3 product search is configured (CHANNEL3_API_KEY)",
        "tags": [
          "Catalog"
        ],
        "summary": "Get product search status",
        "security": [
          {
            "admin": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments": {
      "get": {
        "operationId": "listPayments",
        "description": "List payments",
        "tags": [
          "Payments"
        ],
        "summary": "List payments",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Default 200",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/stuck": {
      "get": {
        "operationId": "listStuckPayments",
        "description": "Payments in reserved/authorized older than a threshold",
        "tags": [
          "Payments"
        ],
        "summary": "List stuck payments",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "older_than_ms",
            "in": "query",
            "description": "Default 60000",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/recover": {
      "post": {
        "operationId": "recoverPayments",
        "description": "Converge stuck payments with PayPal now",
        "tags": [
          "Payments"
        ],
        "summary": "Recover payments",
        "security": [
          {
            "admin": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "older_than_ms": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/receipt": {
      "get": {
        "operationId": "getPaymentReceipt",
        "description": "Receipt for a payment",
        "tags": [
          "Receipts"
        ],
        "summary": "Get payment receipt",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/receipts": {
      "get": {
        "operationId": "listReceipts",
        "description": "List receipts",
        "tags": [
          "Receipts"
        ],
        "summary": "List receipts",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Default 100",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ReceiptSummary"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/receipts/{id}": {
      "get": {
        "operationId": "getReceipt",
        "description": "Receipt by id",
        "tags": [
          "Receipts"
        ],
        "summary": "Get receipt",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/keys/rotate": {
      "post": {
        "operationId": "rotateIssuerKey",
        "description": "Retire the active issuer key and create a new one (audited)",
        "tags": [
          "Keys"
        ],
        "summary": "Rotate issuer key",
        "security": [
          {
            "admin": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/keys/{kid}/compromised": {
      "post": {
        "operationId": "markKeyCompromised",
        "description": "Mark a key compromised as of `at` (rotates first if active)",
        "tags": [
          "Keys"
        ],
        "summary": "Mark key compromised",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "kid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "at": {
                    "type": "string",
                    "description": "ISO time; default now"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/control/pause": {
      "get": {
        "operationId": "getPauseState",
        "description": "Kill-switch state",
        "tags": [
          "Control"
        ],
        "summary": "Get pause state",
        "security": [
          {
            "admin": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PauseState"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "pause",
        "description": "Block every new proposal and approval (503)",
        "tags": [
          "Control"
        ],
        "summary": "Pause",
        "security": [
          {
            "admin": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string"
                  },
                  "by": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/control/resume": {
      "post": {
        "operationId": "resume",
        "description": "Lift the kill-switch",
        "tags": [
          "Control"
        ],
        "summary": "Resume",
        "security": [
          {
            "admin": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "by": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/audit": {
      "get": {
        "operationId": "listAuditEntries",
        "description": "Hash-chained audit log",
        "tags": [
          "Audit"
        ],
        "summary": "List audit entries",
        "security": [
          {
            "admin": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Default 200",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AuditEntry"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/audit/verify": {
      "get": {
        "operationId": "verifyAuditChain",
        "description": "Recompute and verify the whole chain",
        "tags": [
          "Audit"
        ],
        "summary": "Verify audit chain",
        "security": [
          {
            "admin": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditVerification"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/audit/attestation": {
      "get": {
        "operationId": "getAuditAttestation",
        "description": "Chain head signed with the active issuer key",
        "tags": [
          "Audit"
        ],
        "summary": "Get audit attestation",
        "security": [
          {
            "admin": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/audit/anchor": {
      "post": {
        "operationId": "anchorAuditChain",
        "description": "Anchor the chain head now (RFC 6962 Merkle root, RFC 3161 stamped)",
        "tags": [
          "Audit"
        ],
        "summary": "Anchor audit chain",
        "security": [
          {
            "admin": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong bearer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/audit/anchors": {
      "get": {
        "operationId": "listAuditAnchors",
        "description": "Published anchors; keep copies to detect forks",
        "tags": [
          "Audit"
        ],
        "summary": "List audit anchors",
        "security": [],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Default 100",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Body over 256 KB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}