openapi: 3.0.3
info:
  title: AgentPKI Commerce
  description: |
    Public catalog API for AgentPKI Commerce. Discover verified local merchants with
    cryptographically signed catalogs. Suitable for ChatGPT plugins, Claude MCP
    integrations, and any AI agent that wants to recommend real local businesses.
  version: 0.1.0
  contact:
    name: AgentPKI Commerce
    email: hello@agentpki.dev
    url: https://commerce.agentpki.dev
servers:
  - url: https://api-commerce.agentpki.dev
    description: Production
paths:
  /mcp/tools/find_merchants:
    post:
      operationId: findMerchants
      summary: Find local merchants by commerce intent
      description: Returns ranked, verified merchants matching an intent, optional location, vertical, and free-text query.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [intent]
              properties:
                intent:
                  type: string
                  enum: [order_pickup, order_delivery, book_table, book_appointment, book_room, get_quote, inquire_menu, inquire_services, inquire_hours, emergency_service]
                query: { type: string, description: 'Free-text query, e.g. "best deep dish pizza".' }
                location: { type: string, description: 'Metro or neighborhood.' }
                vertical: { type: string, enum: [restaurant, cafe, salon, contractor, retail, other] }
                limit: { type: integer, minimum: 1, maximum: 20, default: 5 }
      responses:
        '200':
          description: Ranked candidates
          content:
            application/json:
              schema:
                type: object
                properties:
                  candidates:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        business_name: { type: string }
                        slug: { type: string }
                        agent_url: { type: string }
                        vertical: { type: string }
                        metro: { type: string }
                        identity_manifest: { type: string }
                        json_ld: { type: string }
  /mcp/tools/get_merchant:
    post:
      operationId: getMerchant
      summary: Get full details for a merchant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchant_id: { type: string, description: 'UUID' }
                slug: { type: string, description: 'Alternative to merchant_id' }
      responses:
        '200':
          description: Merchant detail with signed catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  merchant: { type: object }
                  catalog: { type: object }
                  endpoints: { type: object }
  /mcp/tools/list_intents:
    post:
      operationId: listIntents
      summary: List supported commerce intents
      responses:
        '200':
          description: All intents
          content:
            application/json:
              schema:
                type: object
                properties:
                  intents:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        description: { type: string }
  /catalog:
    get:
      operationId: listCatalog
      summary: Browse all verified merchants
      parameters:
        - { in: query, name: limit, schema: { type: integer, default: 50, maximum: 200 } }
        - { in: query, name: offset, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Paginated merchant list
  /m/{slug}.json:
    get:
      operationId: merchantJsonLd
      summary: JSON-LD schema.org data for a merchant
      parameters:
        - { in: path, name: slug, required: true, schema: { type: string } }
      responses:
        '200':
          description: schema.org structured data with AgentPKI extensions