openapi: 3.1.0
info:
  title: Cometeer Storefront (read-only agent surface)
  version: '2026-08-01'
  summary: Public, unauthenticated JSON endpoints of the Cometeer online store.
  description: |
    Cometeer publishes a read-only browsing surface for agents in its own
    `/llms.txt` under the heading "Read-Only Browsing (No Authentication
    Required)". This document is a faithful OpenAPI rendering of exactly the
    endpoints Cometeer names there, with schemas derived from live observed
    responses on 2026-08-01. It is NOT a Cometeer-authored specification, and
    it is NOT the transactional surface — carts, checkouts and orders are only
    reachable through the UCP MCP endpoint catalogued in
    `mcp/cometeer-mcp.yml`.

    Provenance: generated from https://cometeer.com/llms.txt; every path below
    was probed and returned HTTP 200. No endpoint has been invented.
  contact:
    name: Cometeer Support
    url: https://help.cometeer.com/
  license:
    name: Terms of Service
    url: https://cometeer.com/policies/terms-of-service
  x-provenance:
    generated: '2026-08-01'
    method: generated
    source: https://cometeer.com/llms.txt
    authored_by: API Evangelist enrichment pipeline
    platform: Shopify
servers:
- url: https://cometeer.com
  description: Cometeer production storefront
tags:
- name: Products
  description: Product catalog browsing
- name: Collections
  description: Collection (category) browsing
- name: Search
  description: Storefront search
paths:
  /products.json:
    get:
      operationId: listProducts
      tags: [Products]
      summary: List all products
      description: >-
        Returns the store's published products as JSON. Paginated with `page`
        and `limit`. Documented in Cometeer's /llms.txt as "Browse all
        products".
      parameters:
      - name: limit
        in: query
        description: Number of products per page (Shopify caps this at 250).
        required: false
        schema: {type: integer, minimum: 1, maximum: 250, default: 30}
      - name: page
        in: query
        description: 1-indexed page number.
        required: false
        schema: {type: integer, minimum: 1, default: 1}
      responses:
        '200':
          description: A page of products.
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items: {$ref: '#/components/schemas/Product'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /products/{handle}.json:
    get:
      operationId: getProduct
      tags: [Products]
      summary: Get a single product by handle
      description: Documented in Cometeer's /llms.txt as "Product JSON".
      parameters:
      - name: handle
        in: path
        required: true
        description: The product's URL handle, e.g. `frozen-gold-ember-espresso`.
        schema: {type: string}
      responses:
        '200':
          description: The product.
          content:
            application/json:
              schema:
                type: object
                properties:
                  product: {$ref: '#/components/schemas/Product'}
        '404': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /collections/{handle}/products.json:
    get:
      operationId: listCollectionProducts
      tags: [Collections]
      summary: List products in a collection
      description: >-
        Documented in Cometeer's /llms.txt as "Collection JSON". The `all`
        handle returns every product in the store.
      parameters:
      - name: handle
        in: path
        required: true
        description: The collection's URL handle, e.g. `all`.
        schema: {type: string}
      - name: limit
        in: query
        required: false
        schema: {type: integer, minimum: 1, maximum: 250, default: 30}
      - name: page
        in: query
        required: false
        schema: {type: integer, minimum: 1, default: 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': {$ref: '#/components/responses/NotFound'}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /search:
    get:
      operationId: searchProducts
      tags: [Search]
      summary: Search the storefront
      description: >-
        Documented in Cometeer's /llms.txt as "Search". Returns an HTML results
        page; there is no JSON representation of this endpoint on the
        storefront. Agents needing structured search should use the UCP MCP
        `search_catalog` tool instead (see mcp/cometeer-mcp.yml).
      parameters:
      - name: q
        in: query
        required: true
        description: The search query.
        schema: {type: string}
      - name: type
        in: query
        required: false
        description: Restrict results to a resource type.
        schema: {type: string, enum: [product, article, page]}
      responses:
        '200':
          description: HTML search results page.
          content:
            text/html:
              schema: {type: string}
        '429': {$ref: '#/components/responses/TooManyRequests'}
  /sitemap.xml:
    get:
      operationId: getSitemap
      tags: [Products]
      summary: Store sitemap index
      description: Documented in Cometeer's /llms.txt under "Store Metadata".
      responses:
        '200':
          description: XML sitemap index.
          content:
            application/xml:
              schema: {type: string}
components:
  responses:
    NotFound:
      description: The requested resource does not exist.
      content:
        text/html:
          schema: {type: string}
    TooManyRequests:
      description: >-
        Rate limited. Cometeer's /llms.txt instructs agents to back off on 429
        responses.
      content:
        text/html:
          schema: {type: string}
  schemas:
    Product:
      type: object
      description: A storefront product, as observed in live responses.
      properties:
        id: {type: integer, format: int64}
        title: {type: string}
        handle: {type: string}
        body_html: {type: string}
        published_at: {type: string, format: date-time}
        created_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}
        vendor: {type: string, examples: [Cometeer]}
        product_type: {type: string, examples: [Coffee Sleeve, Merchandise]}
        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']}
        position: {type: integer}
        price: {type: string}
        price_currency: {type: string, examples: [USD]}
        compare_at_price: {type: [string, 'null']}
        compare_at_price_currency: {type: [string, 'null']}
        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}
        quantity_price_breaks: {type: array, 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
      properties:
        id: {type: integer, format: int64}
        product_id: {type: integer, format: int64}
        name: {type: string}
        position: {type: integer}
        values:
          type: array
          items: {type: string}