openapi: 3.1.0
info:
  title: Liquid Death Storefront Read-Only JSON API
  version: '2026-08-01'
  summary: The anonymous, read-only product and collection JSON surface Liquid Death publishes for AI agents.
  description: |
    Liquid Death runs its direct-to-consumer store at https://liquiddeath.com on Shopify. The store
    publishes an agent-facing instruction document at `/agents.md` (mirrored at `/llms.txt`) that
    explicitly documents a **read-only browsing** surface for "agents that only need to read store data
    without transacting". No authentication is required for any operation in this document.

    This OpenAPI was GENERATED by the API Evangelist enrichment pipeline from the endpoints Liquid Death
    documents in `/agents.md`, and every operation below was probed live on 2026-08-01 and confirmed to
    return the recorded status and content type. Schemas were derived from observed response bodies.
    Nothing here is invented: no operation appears that was not both documented by the provider and
    verified against the live host.

    Transactional operations (cart, checkout, order) are **not** in this document. Liquid Death exposes
    those over the Universal Commerce Protocol (UCP) MCP endpoint — see `mcp/liquid-death-mcp.yml` and
    `mcp/liquid-death-ucp-shopping-mcp.openrpc.json`. The provider's robots.txt explicitly directs agents
    to UCP/MCP for catalog, cart and checkout, and disallows scripted checkout completion.
  contact:
    name: Liquid Death
    url: https://liquiddeath.com/pages/summon-us
  termsOfService: https://liquiddeath.com/policies/terms-of-service
  x-generated-by: api-evangelist enrichment pipeline
  x-source-documentation: https://liquiddeath.com/agents.md
  x-probed: '2026-08-01'
servers:
  - url: https://liquiddeath.com
    description: Production storefront
tags:
  - name: Catalog
    description: Product and collection data
  - name: Discovery
    description: Store-level discovery documents for crawlers and agents
paths:
  /products/{handle}.json:
    get:
      operationId: getProduct
      tags: [Catalog]
      summary: Get a product by handle
      description: |
        Returns the full product record for a single product handle, including variants, options and
        images. Documented under "Read-Only Browsing" in https://liquiddeath.com/agents.md as
        `GET /products/{handle}.json`.
      parameters:
        - name: handle
          in: path
          required: true
          description: The product handle (URL slug), e.g. `sparkling-energy-vp2`.
          schema:
            type: string
          example: sparkling-energy-vp2
      responses:
        '200':
          description: The product record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    $ref: '#/components/schemas/Product'
        '404':
          description: No product exists with that handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /collections/{handle}/products.json:
    get:
      operationId: listCollectionProducts
      tags: [Catalog]
      summary: List products in a collection
      description: |
        Returns the products in a collection. The special handle `all` returns the entire catalog.
        Documented in https://liquiddeath.com/agents.md as `GET /collections/{handle}/products.json`
        and `GET /collections/all`.
      parameters:
        - name: handle
          in: path
          required: true
          description: Collection handle, e.g. `water`, `merch-store`, or `all` for the whole catalog.
          schema:
            type: string
          example: all
        - name: limit
          in: query
          required: false
          description: Maximum number of products to return in one page.
          schema:
            type: integer
            minimum: 1
          example: 50
        - name: page
          in: query
          required: false
          description: 1-indexed page number, used with `limit` for offset pagination.
          schema:
            type: integer
            minimum: 1
          example: 1
      responses:
        '200':
          description: A page of products in the collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
        '404':
          description: No collection exists with that handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /search:
    get:
      operationId: searchStorefront
      tags: [Catalog]
      summary: Search the storefront
      description: |
        Full-text storefront search. Documented in https://liquiddeath.com/agents.md as
        `GET /search?q={query}&type=product`. Returns a rendered HTML results page — the store does not
        publish a JSON projection of search. Agents needing structured search results are directed by
        the provider to the UCP `search_catalog` MCP tool instead.
      parameters:
        - name: q
          in: query
          required: true
          description: The search query.
          schema:
            type: string
          example: water
        - name: type
          in: query
          required: false
          description: Restricts the resource types searched.
          schema:
            type: string
            enum: [product, article, page]
          example: product
      responses:
        '200':
          description: An HTML search results page.
          content:
            text/html:
              schema:
                type: string
  /sitemap.xml:
    get:
      operationId: getSitemap
      tags: [Discovery]
      summary: Get the sitemap index
      description: |
        The sitemap index, linking per-locale product, collection, page and blog sitemaps, plus
        `sitemap_agentic_discovery.xml` which points crawlers at `/agents.md`.
      responses:
        '200':
          description: A sitemaps.org sitemap index document.
          content:
            application/xml:
              schema:
                type: string
  /agents.md:
    get:
      operationId: getAgentInstructions
      tags: [Discovery]
      summary: Get the agent instruction document
      description: |
        The canonical agent-facing description of the store: UCP endpoints, supported UCP versions,
        the read-only browsing surface, the buyer-approval rule, and store policies. Mirrored verbatim
        at `/llms.txt`.
      responses:
        '200':
          description: The agent instruction document in Markdown.
          content:
            text/markdown:
              schema:
                type: string
  /llms.txt:
    get:
      operationId: getLlmsTxt
      tags: [Discovery]
      summary: Get the llms.txt document
      description: A mirror of `/agents.md` served at the llms.txt convention path.
      responses:
        '200':
          description: The llms.txt document.
          content:
            text/plain:
              schema:
                type: string
  /.well-known/ucp:
    get:
      operationId: getUcpProfile
      tags: [Discovery]
      summary: Get the UCP merchant profile
      description: |
        The Universal Commerce Protocol merchant discovery profile: supported protocol versions,
        service endpoints (including the MCP transport endpoint), negotiated capabilities, and the
        configured payment handlers. Anonymous.
      responses:
        '200':
          description: The UCP merchant profile.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ucp:
                    type: object
components:
  schemas:
    Product:
      type: object
      description: A storefront product, as returned by the read-only product JSON endpoints.
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        handle:
          type: string
        body_html:
          type: string
          description: Product description as HTML.
        published_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        vendor:
          type: string
        product_type:
          type: string
        template_suffix:
          type: [string, 'null']
        published_scope:
          type: string
        tags:
          type: array
          items:
            type: string
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        image:
          $ref: '#/components/schemas/Image'
        options:
          type: array
          items:
            $ref: '#/components/schemas/Option'
    Variant:
      type: object
      description: A purchasable variant of a product.
      properties:
        id:
          type: integer
          format: int64
        product_id:
          type: integer
          format: int64
        title:
          type: string
        sku:
          type: [string, 'null']
        barcode:
          type: [string, 'null']
        price:
          type: string
        price_currency:
          type: string
        compare_at_price:
          type: [string, 'null']
        compare_at_price_currency:
          type: [string, 'null']
        position:
          type: integer
        option1:
          type: [string, 'null']
        option2:
          type: [string, 'null']
        option3:
          type: [string, 'null']
        grams:
          type: integer
        weight:
          type: number
        weight_unit:
          type: string
        taxable:
          type: boolean
        tax_code:
          type: [string, 'null']
        requires_shipping:
          type: boolean
        fulfillment_service:
          type: [string, 'null']
        inventory_management:
          type: [string, 'null']
        image_id:
          type: [integer, 'null']
          format: int64
        quantity_rule:
          type: object
          description: Minimum/increment purchase constraints for this variant.
        quantity_price_breaks:
          type: array
          description: Volume price breaks for this variant.
          items:
            type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Image:
      type: object
      properties:
        id:
          type: integer
          format: int64
        product_id:
          type: integer
          format: int64
        src:
          type: string
          format: uri
        alt:
          type: [string, 'null']
        width:
          type: integer
        height:
          type: integer
        position:
          type: integer
        variant_ids:
          type: array
          items:
            type: integer
            format: int64
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Option:
      type: object
      description: A product option axis, e.g. Flavors or Size.
      properties:
        name:
          type: string
        position:
          type: integer
        values:
          type: array
          items:
            type: string
    Error:
      type: object
      description: Error body returned by the storefront JSON endpoints.
      properties:
        errors:
          type: string