ProveCart Admin API

openapi: 3.2.0
info:
  title: ProveCart Verification Admin 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: Admin
paths:
  /admin/api-keys:
    post:
      summary: Create Api Key
      description: 'Issue an integrator API key. Guarded by the admin secret

        (INTENTFIT_ADMIN_SECRET when set, else the INTENTFIT_SECRET

        fallback — audit fix F-02). The raw key is returned once.'
      operationId: create_api_key_admin_api_keys_post
      parameters:
      - name: X-Admin-Secret
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admin-Secret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/api-keys/{key_id}/fail-safe:
    post:
      summary: Set Api Key Fail Safe
      description: 'Toggle the fail-safe verdict policy for one API key. With the

        policy OFF the engine returns its legacy verdicts (any hard fail

        BLOCKs); with it ON (the default) uncertainty routes to REVIEW.'
      operationId: set_api_key_fail_safe_admin_api_keys__key_id__fail_safe_post
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      - name: X-Admin-Secret
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admin-Secret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FailSafeIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/api-keys/{key_id}/ai-layer:
    post:
      summary: Set Api Key Ai Layer
      description: 'Toggle the AI layer for one API key. With the layer OFF the key

        gets exactly the pre-AI engine behavior: REVIEW verdicts stand as

        the rules engine issued them, and no AI data appears in responses

        or evidence records.'
      operationId: set_api_key_ai_layer_admin_api_keys__key_id__ai_layer_post
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      - name: X-Admin-Secret
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admin-Secret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiLayerIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/api-keys/{key_id}/verdict-links:
    post:
      summary: Set Api Key Verdict Links
      description: 'Toggle the verdict `links` field for one API key. With the

        field OFF the key''s REVIEW / BLOCK responses carry no `links`

        entry at all — the pointer is gone from that key''s traffic, and

        verdicts, corrections and evidence records are unaffected.'
      operationId: set_api_key_verdict_links_admin_api_keys__key_id__verdict_links_post
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      - name: X-Admin-Secret
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admin-Secret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerdictLinksIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/merchants:
    post:
      summary: Create Merchant
      description: 'Admin-only: create a merchant portal account. Issues (or links)

        the merchant''s API key and returns a ONE-TIME password-set token —

        only its hash is stored, it expires in 48 hours, and it dies on

        first use. The merchant sets their own password; the admin never

        sees or chooses it.'
      operationId: create_merchant_admin_merchants_post
      parameters:
      - name: X-Admin-Secret
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admin-Secret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantCreateIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
  /admin/merchants/{merchant_id}/set-token:
    post:
      summary: Reissue Set Token
      description: 'Admin-only: mint a FRESH password-set token for an existing

        merchant (a lost or expired invite link). Minting invalidates the

        merchant''s earlier unused tokens.'
      operationId: reissue_set_token_admin_merchants__merchant_id__set_token_post
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
          title: Merchant Id
      - name: X-Admin-Secret
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admin-Secret
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin
components:
  schemas:
    VerdictLinksIn:
      properties:
        verdict_links:
          type: boolean
          title: Verdict Links
      type: object
      required:
      - verdict_links
      title: VerdictLinksIn
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MerchantCreateIn:
      properties:
        email:
          type: string
          title: Email
        business_name:
          type: string
          title: Business Name
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        api_key_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key Id
        fail_safe:
          type: boolean
          title: Fail Safe
          default: true
        ai_layer:
          type: boolean
          title: Ai Layer
          default: true
        verdict_links:
          type: boolean
          title: Verdict Links
          default: true
      type: object
      required:
      - email
      - business_name
      title: MerchantCreateIn
    AiLayerIn:
      properties:
        ai_layer:
          type: boolean
          title: Ai Layer
      type: object
      required:
      - ai_layer
      title: AiLayerIn
    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
    FailSafeIn:
      properties:
        fail_safe:
          type: boolean
          title: Fail Safe
      type: object
      required:
      - fail_safe
      title: FailSafeIn
    ApiKeyIn:
      properties:
        label:
          type: string
          title: Label
          default: integrator
        fail_safe:
          type: boolean
          title: Fail Safe
          default: true
        ai_layer:
          type: boolean
          title: Ai Layer
          default: true
        verdict_links:
          type: boolean
          title: Verdict Links
          default: true
      type: object
      title: ApiKeyIn
externalDocs:
  description: 'ProveCart for agents: practice, certification, scoreboard'
  url: https://provecart.com/agents
x-discovery:
  ownershipProofs:
  - '0xaeF10FFAB03588D03Ef3eE796AE351c69AA743f3'