openapi: 3.1.0
info:
  title: Brooklinen Shopify Storefront JSON API
  version: '2026-08-02'
  summary: Read-only JSON endpoints over the Brooklinen Shopify storefront.
  description: >-
    Unauthenticated, read-only JSON endpoints over the Brooklinen storefront at https://www.brooklinen.com.
    Brooklinen documents this surface itself, in the "Read-Only Browsing (No Authentication Required)"
    section of https://www.brooklinen.com/agents.md (mirrored at /llms.txt), for agents that need to read
    store data without transacting.


    NOT A PROVIDER-PUBLISHED SPEC. Brooklinen publishes no OpenAPI document. This description was generated
    by the API Evangelist enrichment pipeline from (a) the endpoint list Brooklinen publishes in /agents.md
    and (b) live probes of each endpoint on 2026-08-02. Every path below returned HTTP 200 when probed and
    every schema property below was observed in a real response body — nothing here is invented. Per-operation
    `x-evidence` records the probe. For transactional operations (cart, checkout, order) see the UCP/MCP
    surface at https://www.brooklinen.com/api/ucp/mcp, described in mcp/brooklinen-mcp.yml.
  contact:
    name: Brooklinen
    url: https://www.brooklinen.com/pages/contact
  termsOfService: https://www.brooklinen.com/policies/terms-of-service
  x-generated: '2026-08-02'
  x-method: generated
  x-source: https://www.brooklinen.com/agents.md
servers:
- url: https://www.brooklinen.com
  description: Brooklinen production storefront (Shopify)
tags:
- name: Products
  description: Product catalog listing and detail.
- name: Collections
  description: Products grouped into merchandising collections.
- name: Search
  description: Predictive storefront search.
- name: Cart
  description: Read-only view of the current session cart.
- name: Discovery
  description: Sitemaps and agent discovery documents.
paths:
  /products.json:
    get:
      operationId: listProducts
      tags:
      - Products
      summary: List products
      description: >-
        Returns the store's published products with their variants, images and options. Paginated with
        `limit` and `page`.
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A page of products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-evidence:
        fetched: '2026-08-02'
        url: https://www.brooklinen.com/products.json?limit=1
        http_status: 200
        content_type: application/json; charset=utf-8
  /products/{handle}.json:
    get:
      operationId: getProduct
      tags:
      - Products
      summary: Get a product by handle
      description: Returns a single published product, addressed by its URL handle.
      parameters:
      - $ref: '#/components/parameters/Handle'
      responses:
        '200':
          description: The product.
          content:
            application/json:
              schema:
                type: object
                required:
                - product
                properties:
                  product:
                    $ref: '#/components/schemas/Product'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-evidence:
        fetched: '2026-08-02'
        url: https://www.brooklinen.com/products/dreamweave-waffle-robe-last-call.json
        http_status: 200
        content_type: application/json; charset=utf-8
  /collections/{handle}/products.json:
    get:
      operationId: listCollectionProducts
      tags:
      - Collections
      summary: List products in a collection
      description: >-
        Returns the published products in a merchandising collection. The `all` handle returns the full
        catalog.
      parameters:
      - $ref: '#/components/parameters/Handle'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A page of products in the collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-evidence:
        fetched: '2026-08-02'
        url: https://www.brooklinen.com/collections/all/products.json?limit=1&page=1
        http_status: 200
        content_type: application/json; charset=utf-8
  /search/suggest.json:
    get:
      operationId: suggestSearch
      tags:
      - Search
      summary: Predictive search suggestions
      description: >-
        Returns predictive search results for a query. Brooklinen's /agents.md documents storefront search as
        `GET /search?q={query}&type=product`, which renders HTML; this JSON variant was probed live and
        returns structured product results.
      parameters:
      - name: q
        in: query
        required: true
        description: The search query.
        schema:
          type: string
        example: sheets
      - name: resources[type]
        in: query
        required: false
        description: Comma-separated resource types to search (e.g. `product`, `collection`, `page`, `article`).
        schema:
          type: string
        example: product
      responses:
        '200':
          description: Predictive search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchSuggestions'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-evidence:
        fetched: '2026-08-02'
        url: https://www.brooklinen.com/search/suggest.json?q=sheets&resources%5Btype%5D=product
        http_status: 200
        content_type: application/json; charset=utf-8
  /cart.js:
    get:
      operationId: getCart
      tags:
      - Cart
      summary: Get the current session cart
      description: >-
        Returns the cart bound to the caller's session cookie. Anonymous callers receive a new, empty cart.
        Transactional cart and checkout operations are on the UCP/MCP surface, not here.
      responses:
        '200':
          description: The session cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-evidence:
        fetched: '2026-08-02'
        url: https://www.brooklinen.com/cart.js
        http_status: 200
        content_type: text/javascript; charset=utf-8
  /agents.md:
    get:
      operationId: getAgentInstructions
      tags:
      - Discovery
      summary: Get the store's agent instruction document
      description: >-
        The canonical agent-facing description of the store, listed in /robots.txt and in
        /sitemap_agentic_discovery.xml. Mirrored at /llms.txt.
      responses:
        '200':
          description: Agent instructions in Markdown.
          content:
            text/markdown:
              schema:
                type: string
      x-evidence:
        fetched: '2026-08-02'
        url: https://www.brooklinen.com/agents.md
        http_status: 200
        content_type: text/markdown; charset=utf-8
  /.well-known/ucp:
    get:
      operationId: getUcpProfile
      tags:
      - Discovery
      summary: Get the UCP merchant discovery profile
      description: >-
        Returns the store's Universal Commerce Protocol merchant profile — supported protocol versions,
        service endpoints (including the MCP endpoint), negotiated capabilities and payment handlers.
      responses:
        '200':
          description: The UCP merchant profile.
          content:
            application/json:
              schema:
                type: object
      x-evidence:
        fetched: '2026-08-02'
        url: https://www.brooklinen.com/.well-known/ucp
        http_status: 200
        content_type: application/json; charset=utf-8
  /sitemap.xml:
    get:
      operationId: getSitemapIndex
      tags:
      - Discovery
      summary: Get the sitemap index
      description: >-
        Parent sitemap linking to the agentic discovery, product, page, collection and blog sitemaps.
      responses:
        '200':
          description: Sitemap index XML.
          content:
            application/xml:
              schema:
                type: string
      x-evidence:
        fetched: '2026-08-02'
        url: https://www.brooklinen.com/sitemap.xml
        http_status: 200
        content_type: application/xml; charset=utf-8
components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Number of products to return per page.
      schema:
        type: integer
        minimum: 1
      example: 1
    Page:
      name: page
      in: query
      required: false
      description: 1-indexed page number.
      schema:
        type: integer
        minimum: 1
      example: 1
    Handle:
      name: handle
      in: path
      required: true
      description: The URL handle of the resource.
      schema:
        type: string
      example: dreamweave-waffle-robe-last-call
  responses:
    NotFound:
      description: The requested resource does not exist.
    RateLimited:
      description: >-
        Too many requests. Brooklinen's /agents.md instructs agents to back off on 429 responses.
  schemas:
    ProductList:
      type: object
      required:
      - products
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    Product:
      type: object
      description: A published storefront product. Properties observed in a live /products.json response.
      properties:
        id:
          type: integer
          description: Shopify product identifier.
        title:
          type: string
        handle:
          type: string
          description: URL slug used to address the product.
        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
        tags:
          type: array
          items:
            type: string
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
        images:
          type: array
          items:
            $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
        product_id:
          type: integer
          description: Identifier of the parent product.
        title:
          type: string
        option1:
          type:
          - string
          - 'null'
        option2:
          type:
          - string
          - 'null'
        option3:
          type:
          - string
          - 'null'
        sku:
          type:
          - string
          - 'null'
        price:
          type: string
        compare_at_price:
          type:
          - string
          - 'null'
        available:
          type: boolean
        requires_shipping:
          type: boolean
        taxable:
          type: boolean
        grams:
          type: integer
        position:
          type: integer
        featured_image:
          anyOf:
          - $ref: '#/components/schemas/Image'
          - type: 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Image:
      type: object
      properties:
        id:
          type: integer
        product_id:
          type: integer
        variant_ids:
          type: array
          items:
            type: integer
        src:
          type: string
          format: uri
        width:
          type: integer
        height:
          type: integer
        position:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Option:
      type: object
      properties:
        name:
          type: string
        position:
          type: integer
        values:
          type: array
          items:
            type: string
    SearchSuggestions:
      type: object
      description: Predictive search envelope observed on /search/suggest.json.
      properties:
        resources:
          type: object
          properties:
            results:
              type: object
              properties:
                products:
                  type: array
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                      handle:
                        type: string
                      url:
                        type: string
                      body:
                        type: string
                      available:
                        type: boolean
                      price:
                        type: string
    Cart:
      type: object
      description: The session cart, as observed on /cart.js.
      properties:
        token:
          type: string
        note:
          type:
          - string
          - 'null'
        attributes:
          type: object
        original_total_price:
          type: integer
        total_price:
          type: integer
        total_discount:
          type: integer
        total_weight:
          type: number
        item_count:
          type: integer
        requires_shipping:
          type: boolean
        currency:
          type: string
        items:
          type: array
          items:
            type: object