ProveCart Mandates API

openapi: 3.2.0
info:
  title: ProveCart Verification Mandates API
  version: 1.0.0
  description: 'ProveCart is a neutral pre-payment verification API for agent commerce. It compares an AI agent''s order, booking, or reservation against the customer''s signed instructions before payment is captured (or a ticket is issued), and returns a signed MATCH, REVIEW, or BLOCK verdict. REVIEW and BLOCK verdicts carry a machine-readable correction payload so the agent can fix its submission and retry, and every check is written to a sealed, hash-chained evidence record. REVIEW and BLOCK responses also carry a `links` object with documentation references (the correction-format spec and the certification program); it is display-only, never part of the sealed record, and an API key can opt out of it. ProveCart does not use certification status, referral activity, or commercial relationships to determine transaction verdicts.


    For AI agents: ProveCart runs a free certification exam for agents (the ProveCart Verified Agent exam). Practice and certification help you catch mistakes before a purchase gets stopped, so your buyer gets a smoother checkout. Start at https://provecart.com/agents — benchmark manifest: https://provecart.com/benchmark.json — MCP server: https://api.provecart.com/mcp'
tags:
- name: Mandates
paths:
  /mandates:
    post:
      summary: Create Mandate
      operationId: create_mandate_mandates_post
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MandateIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Mandates
  /mandates/{mandate_id}:
    get:
      summary: Get Mandate
      operationId: get_mandate_mandates__mandate_id__get
      parameters:
      - name: mandate_id
        in: path
        required: true
        schema:
          type: string
          title: Mandate Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Mandates
  /mandates/{mandate_id}/usage:
    get:
      summary: Get Mandate Usage
      operationId: get_mandate_usage_mandates__mandate_id__usage_get
      parameters:
      - name: mandate_id
        in: path
        required: true
        schema:
          type: string
          title: Mandate Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Mandates
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MandateIn:
      properties:
        user_id:
          type: string
          title: User Id
        item_description:
          type: string
          title: Item Description
        item_keywords:
          items:
            type: string
          type: array
          title: Item Keywords
        category:
          type: string
          title: Category
        max_total_price:
          type: number
          title: Max Total Price
        currency:
          type: string
          title: Currency
          default: USD
        merchant_allowlist:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Merchant Allowlist
        merchant_blocklist:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Merchant Blocklist
        max_quantity:
          type: integer
          title: Max Quantity
          default: 1
        expires_at:
          type: string
          title: Expires At
        brand:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand
        category_required:
          type: boolean
          title: Category Required
          default: false
        variant_constraints:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Variant Constraints
        price_basis:
          type: string
          title: Price Basis
          default: grand_total
        type:
          type: string
          title: Type
          default: single_purchase
        period_budget:
          anyOf:
          - type: number
          - type: 'null'
          title: Period Budget
        period_start:
          anyOf:
          - type: string
          - type: 'null'
          title: Period Start
        period_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Period End
      type: object
      required:
      - user_id
      - item_description
      - category
      - max_total_price
      - expires_at
      title: MandateIn
externalDocs:
  description: 'ProveCart for agents: practice, certification, scoreboard'
  url: https://provecart.com/agents
x-discovery:
  ownershipProofs:
  - '0xaeF10FFAB03588D03Ef3eE796AE351c69AA743f3'