openapi: 3.1.0
info:
  title: Bossert Custom Dog Tags Agent API
  version: "1.0"
  description: >-
    Order custom stamped dog tags from Bossert's Military Surplus (Kansas
    City, US). Agents configure the order; payment is always completed by a
    human via the returned Stripe hosted checkout link, which expires after
    30 minutes. An MCP server with the same
    capability is at https://dogtag.bossertmilsurp.com/api/mcp (streamable HTTP; tools get_catalog,
    price_quote, create_checkout). Machine readable catalog with
    authoritative integer cent prices at https://dogtag.bossertmilsurp.com/products.json.
servers:
  - url: https://dogtag.bossertmilsurp.com
paths:
  /products.json:
    get:
      summary: Machine readable catalog (authoritative prices and constraints)
      responses:
        "200":
          description: The catalog
  /api/agent-checkout:
    post:
      summary: Create an order and get a Stripe hosted payment link for a human to pay
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [fulfillment, items]
              properties:
                fulfillment:
                  type: string
                  enum: [ship, pickup]
                items:
                  type: array
                  minItems: 1
                  maxItems: 3
                  items:
                    type: object
                    additionalProperties: false
                    required: [styleKey, tag1, tag2, silencers, debossing, qty]
                    properties:
                      styleKey:
                        type: string
                        enum: [standard_ss, polished_black, notched_wwii, brass_le, medical_single]
                      tag1:
                        type: array
                        minItems: 1
                        maxItems: 5
                        items:
                          type: string
                          maxLength: 17
                        description: 'Uppercased before stamping. Allowed characters match the regex ^[A-Z0-9 \-./#(),&'']*$'
                      tag2:
                        description: Must be null for medical_single (single face tag)
                        oneOf:
                          - type: "null"
                          - type: array
                            minItems: 1
                            maxItems: 5
                            items:
                              type: string
                              maxLength: 17
                      silencers:
                        type: boolean
                      debossing:
                        type: boolean
                      qty:
                        type: integer
                        minimum: 1
                        maximum: 20
                agent:
                  type: object
                  additionalProperties: false
                  properties:
                    name:
                      type: string
                      maxLength: 120
                    url:
                      type: string
                      maxLength: 120
                    contact:
                      type: string
                      maxLength: 120
      responses:
        "200":
          description: Order created. A human must open and pay checkout_url before it expires.
        "400":
          description: Validation failure. Stable codes include unknown_field, bad_fulfillment, empty_cart, cart_too_large, unknown_style, bad_quantity, bad_tag_text, tag2_on_single, bad_agent.
        "429":
          description: Rate limited. Retry after the retry-after header seconds.
        "502":
          description: Upstream failure (blobs_error or stripe_error). Retry later.
