AgentPay Labs Commerce API

openapi: 3.2.0
info:
  title: AgentPay Commerce API
  description: '**AgentPay public API for Bro and train-first agent commerce.**

    This OpenAPI document is limited to the Cloudflare Workers production surface.

    Legacy Node-only routes are intentionally excluded until they are migrated.


    ## Authentication

    All protected endpoints require an API key via:

    - `Authorization: Bearer ` header, or

    - `X-Api-Key: ` header


    ## Protocols Supported

    - **x402** — HTTP 402 paywall standard

    - **ACP** — Agent Communication Protocol

    - **AP2** — Agent Payment Protocol v2

    - **Solana Pay** — Solana USDC native

    - **Stripe** — Fiat card / bank payments


    Get your API key: `POST /api/merchants/register`'
  version: 1.0.0
  contact:
    name: AgentPay Support
    url: https://docs.agentpay.gg
    email: support@agentpay.gg
  license:
    name: BSL-1.1; AGPL-3.0 after 2029-01-01
    url: https://github.com/Rumblingb/Agentpay/blob/main/LICENSE
servers:
- url: https://api.agentpay.so
  description: Production (Cloudflare Workers)
- url: http://localhost:8787
  description: Local Workers dev (wrangler dev)
tags:
- name: Commerce
  description: Need-led product discovery and closed-world AI decision compilation
paths:
  /api/commerce/compile:
    post:
      tags:
      - Commerce
      summary: Compile a governed product shortlist
      description: 'Applies the human-owned Buyer Constitution''s deterministic category, merchant, stock,

        currency, budget, refundability, delivery, returns, catalog-freshness, and minimum-fit

        constraints before optional GPT-5.6 ranking. The model receives only

        opaque candidate references and structured numeric evidence; product text, raw product

        IDs, checkout URLs, merchant identity, sponsorship, payment data, and free-form customer

        text are excluded.


        Model output must rank every eligible product exactly once using enumerated rationale

        codes. Invalid, missing, duplicated, invented, timed-out, or unavailable model output

        falls back to deterministic rank. The complete discovery and compilation packet is

        returned with an HMAC-SHA256 signature. This endpoint does not execute checkout,

        verify merchant feeds, or collect attribution fees.'
      operationId: compileCommerceDecision
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommerceCompileRequest'
      responses:
        '200':
          description: Signed, policy-constrained commerce compilation packet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommerceCompileResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          description: Isolate, shopper, or merchant compiler capacity exceeded; retry after the response header interval
          headers:
            Retry-After:
              schema:
                type: integer
            X-RateLimit-Limit:
              schema:
                type: integer
                const: 6
            X-AgentPay-Rate-Scope:
              schema:
                type: string
                enum:
                - shopper
                - merchant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Packet signing or model-funded compiler rate control is not configured
components:
  responses:
    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnauthorizedError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CommerceCompilation:
      type: object
      additionalProperties: false
      required:
      - schema
      - source
      - model
      - selectedProductId
      - alternateProductId
      - confidence
      - ranking
      - verification
      - fallbackReason
      - retention
      properties:
        schema:
          type: string
          const: agentpay.commerce-compilation/1.0
        source:
          type: string
          enum:
          - gpt-5.6-verified
          - deterministic
        model:
          type:
          - string
          - 'null'
        selectedProductId:
          type:
          - string
          - 'null'
        alternateProductId:
          type:
          - string
          - 'null'
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
        ranking:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - productId
            - rationaleCodes
            properties:
              productId:
                type: string
              rationaleCodes:
                type: array
                minItems: 1
                maxItems: 3
                items:
                  type: string
                  enum:
                  - strongest_need_fit
                  - catalog_truth_leader
                  - quality_leader
                  - budget_fit
                  - returns_strength
                  - balanced_choice
        verification:
          type: object
          additionalProperties: false
          required:
          - hardConstraintsAppliedBeforeModel
          - candidateSetPreserved
          - checkoutDataSharedWithModel
          - sponsorshipSharedWithModel
          - freeformClaimsAllowed
          properties:
            hardConstraintsAppliedBeforeModel:
              type: boolean
              const: true
            candidateSetPreserved:
              type: boolean
              const: true
            checkoutDataSharedWithModel:
              type: boolean
              const: false
            sponsorshipSharedWithModel:
              type: boolean
              const: false
            freeformClaimsAllowed:
              type: boolean
              const: false
        fallbackReason:
          type:
          - string
          - 'null'
          enum:
          - not_configured
          - no_eligible_products
          - provider_error
          - timeout
          - invalid_model_output
          - null
        retention:
          type: string
          const: not-stored
    CommerceProductCandidate:
      type: object
      additionalProperties: false
      required:
      - id
      - merchantId
      - merchantName
      - title
      - category
      - priceMinor
      - currency
      - availability
      - checkoutUrl
      - imageUrl
      - deliveryDays
      - returnWindowDays
      - refundable
      - catalogUpdatedAt
      - truthScore
      - qualityScore
      - needSignals
      properties:
        id:
          type: string
          maxLength: 200
        merchantId:
          type: string
          maxLength: 200
        merchantName:
          type: string
          maxLength: 300
        title:
          type: string
          maxLength: 500
        category:
          type: string
          maxLength: 120
          pattern: ^[a-z0-9]+(?:[-_][a-z0-9]+)*$
        priceMinor:
          type: integer
          minimum: 0
          maximum: 100000000000
        currency:
          type: string
          pattern: ^[A-Za-z]{3}$
        availability:
          type: string
          enum:
          - in_stock
          - out_of_stock
          - preorder
          - backorder
        checkoutUrl:
          type: string
          format: uri
          pattern: ^https://
        imageUrl:
          type: string
          format: uri
          pattern: ^https://
        deliveryDays:
          type: integer
          minimum: 0
          maximum: 3650
        returnWindowDays:
          type: integer
          minimum: 0
          maximum: 3650
        refundable:
          type: boolean
        catalogUpdatedAt:
          type: string
          format: date-time
        truthScore:
          type: integer
          minimum: 0
          maximum: 100
        qualityScore:
          type: integer
          minimum: 0
          maximum: 100
        needSignals:
          type: array
          minItems: 1
          maxItems: 30
          items:
            type: object
            additionalProperties: false
            required:
            - need
            - score
            properties:
              need:
                type: string
                maxLength: 80
              score:
                type: integer
                minimum: 0
                maximum: 100
        sponsored:
          type: boolean
          default: false
    CommerceCompileRequest:
      type: object
      additionalProperties: false
      required:
      - need
      - constitution
      - products
      properties:
        need:
          type: string
          maxLength: 80
          pattern: ^[a-zA-Z0-9]+(?:[ -][a-zA-Z0-9]+)*$
          example: rain-ready-commute
        constitution:
          $ref: '#/components/schemas/BuyerConstitution'
        limit:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
        products:
          type: array
          minItems: 1
          maxItems: 200
          items:
            $ref: '#/components/schemas/CommerceProductCandidate'
    CommerceCompileResponse:
      type: object
      additionalProperties: false
      required:
      - packet
      - signature
      properties:
        packet:
          type: object
          additionalProperties: false
          required:
          - schema
          - discovery
          - compilation
          properties:
            schema:
              type: string
              const: agentpay.commerce-compilation-packet/1.1
            discovery:
              $ref: '#/components/schemas/CommerceDiscoveryReport'
            compilation:
              $ref: '#/components/schemas/CommerceCompilation'
        signature:
          $ref: '#/components/schemas/SignedPacketSignature'
    BuyerConstitution:
      type: object
      additionalProperties: false
      description: Human-owned hard limits enforced before any model ranking.
      required:
      - currency
      - maxTotalMinor
      - allowedCategories
      properties:
        currency:
          type: string
          pattern: ^[A-Za-z]{3}$
          example: GBP
        maxTotalMinor:
          type: integer
          minimum: 1
          maximum: 100000000000
          example: 15000
        allowedCategories:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
            maxLength: 120
          example:
          - bags
          - clothing
        allowedMerchants:
          type: array
          maxItems: 100
          items:
            type: string
            maxLength: 120
        blockedMerchants:
          type: array
          maxItems: 100
          items:
            type: string
            maxLength: 120
        requiresRefundable:
          type: boolean
          default: false
        minimumReturnWindowDays:
          type: integer
          minimum: 0
          maximum: 3650
        maximumDeliveryDays:
          type: integer
          minimum: 0
          maximum: 3650
        maxEvidenceAgeMinutes:
          type: integer
          minimum: 1
          maximum: 525600
          default: 1440
        requireHumanApproval:
          type: boolean
          default: true
        autoApproveBelowMinor:
          type: integer
          minimum: 1
          maximum: 100000000000
        weights:
          type: object
          additionalProperties: false
          properties:
            price:
              type: number
              minimum: 0
              maximum: 100
            quality:
              type: number
              minimum: 0
              maximum: 100
            delivery:
              type: number
              minimum: 0
              maximum: 100
            sustainability:
              type: number
              minimum: 0
              maximum: 100
    CommerceDiscoveryReport:
      type: object
      description: Constitution-constrained deterministic discovery result over caller-supplied candidates.
      required:
      - schema
      - need
      - evaluatedAt
      - constitution
      - rankingPolicy
      - catalogProvenance
      - matches
      - rejected
      - retention
      properties:
        schema:
          type: string
          const: agentpay.product-discovery/1.1
        need:
          type: string
        evaluatedAt:
          type: string
          format: date-time
        constitution:
          $ref: '#/components/schemas/BuyerConstitution'
        rankingPolicy:
          type: object
          properties:
            paidPlacementChangesOrganicRank:
              type: boolean
              const: false
            hardFilters:
              type: array
              items:
                type: string
            weights:
              type: object
              additionalProperties:
                type: number
        catalogProvenance:
          type: object
          required:
          - source
          - merchantConnection
          - warning
          properties:
            source:
              type: string
              const: caller_supplied_candidates
            merchantConnection:
              type: string
              const: not_verified
            warning:
              type: string
        matches:
          type: array
          items:
            type: object
            required:
            - product
            - fitScore
            - rank
            - reasons
            - disclosure
            - attributionDraft
            properties:
              product:
                $ref: '#/components/schemas/CommerceProductCandidate'
              fitScore:
                type: integer
                minimum: 0
                maximum: 100
              rank:
                type: integer
                minimum: 1
              reasons:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      enum:
                      - NEED_FIT
                      - CATALOG_TRUTH
                      - QUALITY
                      - BUDGET_FIT
                      - RETURNS
                    score:
                      type: integer
                      minimum: 0
                      maximum: 100
              disclosure:
                type: string
                enum:
                - organic
                - sponsored
              attributionDraft:
                type: object
                description: Non-binding draft; merchant agreement and verified conversion webhook are required.
                additionalProperties: true
        rejected:
          type: array
          items:
            type: object
            properties:
              productId:
                type: string
              reasonCodes:
                type: array
                items:
                  type: string
        retention:
          type: string
          const: not-stored
    SignedPacketSignature:
      type: object
      additionalProperties: false
      required:
      - algorithm
      - keyId
      - value
      properties:
        algorithm:
          type: string
          const: HMAC-SHA256
        keyId:
          type: string
          const: agentpay-commerce-compiler-v1
        value:
          type: string
          pattern: ^[a-f0-9]{64}$
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: array
          items:
            type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: ''Bearer <api_key>'' or just ''<api_key>'''