openapi: 3.1.0
info:
  title: ALSO Storefront JSON API
  version: '2026-08-02'
  summary: Read-only JSON storefront endpoints ALSO publishes for agents at ridealso.com.
  description: |
    ALSO does not publish an OpenAPI document. This description was **generated by API Evangelist**
    from the read-only endpoints ALSO itself enumerates for agents in its published
    `/agents.md` (mirrored at `/llms.txt`), and every path below was probed live against
    `https://ridealso.com` on 2026-08-02 with the observed HTTP status recorded in
    `x-evidence`. Schemas were derived from the actual response bodies returned by those
    probes - no field is asserted that was not observed.

    This is an AE-generated contract for a real, callable surface. It is **not** a document
    published or endorsed by ALSO. The provider's own machine-readable contracts are the
    Storefront GraphQL schema (`graphql/also-storefront-2026-07.graphql`, captured by open
    introspection) and the UCP profile at `/.well-known/ucp`.
  contact:
    name: ALSO Media
    email: media@ridealso.com
    url: https://ridealso.com/pages/contact
  x-generated-by: API Evangelist enrichment pipeline (local-v1)
  x-provider-published: false
  x-source: https://ridealso.com/agents.md
servers:
- url: https://ridealso.com
  description: ALSO storefront (Shopify-hosted, primary domain)
tags:
- name: Products
  description: Product catalog listings and per-product detail.
- name: Collections
  description: Collection listings and the products within a collection.
- name: Search
  description: Storefront search.
- name: Cart
  description: The current session cart.
paths:
  /products.json:
    get:
      operationId: listProducts
      summary: List all published products
      description: Returns every published product on the storefront. Observed 23 products
        on 2026-08-02.
      tags: [Products]
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum number of products to return per page.
        schema: {type: integer, minimum: 1, maximum: 250}
      - name: page
        in: query
        required: false
        description: Page number for pagination.
        schema: {type: integer, minimum: 1}
      responses:
        '200':
          description: A list of published products.
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items: {$ref: '#/components/schemas/Product'}
      x-evidence:
        fetched: '2026-08-02'
        url: https://ridealso.com/products.json
        http_status: 200
        content_type: application/json; charset=utf-8
  /products/{handle}.json:
    get:
      operationId: getProduct
      summary: Get one product by handle
      tags: [Products]
      parameters:
      - name: handle
        in: path
        required: true
        description: The product handle, e.g. `tm-b`.
        schema: {type: string}
        example: tm-b
      responses:
        '200':
          description: The product.
          content:
            application/json:
              schema:
                type: object
                properties:
                  product: {$ref: '#/components/schemas/Product'}
        '404':
          description: No published product exists with that handle.
          content:
            application/json:
              schema: {type: object}
      x-evidence:
        fetched: '2026-08-02'
        url: https://ridealso.com/products/tm-b.json
        http_status: 200
        not_found_probe: {url: 'https://ridealso.com/products/does-not-exist.json', http_status: 404}
  /collections.json:
    get:
      operationId: listCollections
      summary: List all published collections
      tags: [Collections]
      responses:
        '200':
          description: A list of published collections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  collections:
                    type: array
                    items: {$ref: '#/components/schemas/Collection'}
      x-evidence:
        fetched: '2026-08-02'
        url: https://ridealso.com/collections.json
        http_status: 200
  /collections/{handle}/products.json:
    get:
      operationId: listCollectionProducts
      summary: List the products in a collection
      description: Returns the published products in a collection. Note - an unknown
        collection handle was observed returning HTTP 200 with an empty product list
        rather than 404.
      tags: [Collections]
      parameters:
      - name: handle
        in: path
        required: true
        description: The collection handle, e.g. `gear`.
        schema: {type: string}
        example: gear
      - name: limit
        in: query
        required: false
        schema: {type: integer, minimum: 1, maximum: 250}
      - name: page
        in: query
        required: false
        schema: {type: integer, minimum: 1}
      responses:
        '200':
          description: The products in the collection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items: {$ref: '#/components/schemas/Product'}
      x-evidence:
        fetched: '2026-08-02'
        url: https://ridealso.com/collections/does-not-exist/products.json
        http_status: 200
  /cart.js:
    get:
      operationId: getCart
      summary: Get the current session cart
      description: Returns the cart bound to the caller's session cookie. An anonymous
        caller receives an empty cart.
      tags: [Cart]
      responses:
        '200':
          description: The current cart.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Cart'}
      x-evidence:
        fetched: '2026-08-02'
        url: https://ridealso.com/cart.js
        http_status: 200
        content_type: text/javascript; charset=utf-8
  /search:
    get:
      operationId: searchStorefront
      summary: Search the storefront
      description: Storefront search. Returns an HTML results page, not JSON - listed
        here because ALSO advertises it to agents in agents.md.
      tags: [Search]
      parameters:
      - name: q
        in: query
        required: true
        description: The search query.
        schema: {type: string}
      - name: type
        in: query
        required: false
        description: Resource type to search.
        schema: {type: string, enum: [product, article, page]}
      responses:
        '200':
          description: An HTML search results page.
          content:
            text/html:
              schema: {type: string}
      x-evidence:
        fetched: '2026-08-02'
        url: https://ridealso.com/agents.md
        http_status: 200
        note: advertised in the provider's own agents.md
components:
  schemas:
    Product:
      type: object
      description: A published storefront product.
      properties:
        id: {type: integer, description: Numeric product identifier.}
        title: {type: string}
        handle: {type: string, description: URL slug for the product.}
        body_html: {type: string, description: HTML product description.}
        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, description: 'Observed values include Vehicle,
            Module: Top Frame, Clothing, Hats.'}
        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: The parent product id.}
        title: {type: string}
        option1: {type: [string, 'null']}
        option2: {type: [string, 'null']}
        option3: {type: [string, 'null']}
        sku: {type: [string, 'null']}
        requires_shipping: {type: boolean}
        taxable: {type: boolean}
        featured_image: {oneOf: [{$ref: '#/components/schemas/Image'}, {type: 'null'}]}
        available: {type: boolean}
        price: {type: string, description: Price as a decimal string.}
        compare_at_price: {type: [string, 'null']}
        grams: {type: integer}
        position: {type: integer}
        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}
    Collection:
      type: object
      properties:
        id: {type: integer}
        title: {type: string}
        handle: {type: string}
        description: {type: string}
        image: {oneOf: [{$ref: '#/components/schemas/Image'}, {type: 'null'}]}
        products_count: {type: integer}
        published_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}
    Cart:
      type: object
      description: The session cart as returned by /cart.js.
      properties:
        token: {type: string}
        note: {type: [string, 'null']}
        attributes: {type: object}
        currency: {type: string}
        item_count: {type: integer}
        items:
          type: array
          items: {type: object}
        items_subtotal_price: {type: integer}
        original_total_price: {type: integer}
        total_price: {type: integer}
        total_discount: {type: integer}
        total_weight: {type: number}
        requires_shipping: {type: boolean}
        cart_level_discount_applications:
          type: array
          items: {type: object}
        discount_codes:
          type: array
          items: {type: object}