Liquid Death Catalog API

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.
  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:
    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
    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
    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