openapi: 3.2.0
info:
  title: Liquid Death Storefront Read-Only JSON Catalog 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
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
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'
    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
    Error:
      type: object
      description: Error body returned by the storefront JSON endpoints.
      properties:
        errors:
          type: string
    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
    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