read.products

List published products in a store; filter by category (ltree), SKU option, price range and facetable custom fields; sort; opt-in facets. projection selects a NAMED shape of the result (absent = the whole document; see the projections on the reference page).

• Surface: GET /v1/read/products · CLI forge read products · MCP tool read.products
• Auth: public (no actor; store resolves the tenant)

Params (JSON Schema)

{
  "additionalProperties": {
    "type": "string"
  },
  "properties": {
    "category": {
      "pattern": "^[A-Za-z0-9_]+(\\.[A-Za-z0-9_]+)*$",
      "type": "string"
    },
    "collection": {
      "minLength": 1,
      "type": "string"
    },
    "limit": {
      "default": 24,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "page": {
      "default": 1,
      "maximum": 9007199254740991,
      "minimum": 1,
      "type": "integer"
    },
    "projection": {
      "description": "Named projection of the result. Declared: full, feed. Absent = full.",
      "type": "string"
    },
    "status": {
      "enum": [
        "draft",
        "active",
        "archived"
      ],
      "type": "string"
    },
    "store": {
      "minLength": 1,
      "type": "string"
    }
  },
  "type": "object"
}

Result (200)

Open (unknown) — this capability does not declare an output schema.

Projections

Pass projection=<name>. An absent projection means full — an existing caller is unaffected. A name that is not declared here is refused (unknown_projection), never served as the default.

projection=full

The whole product document, exactly as this read has always served it. This is what an absent projection means, so an existing caller is unaffected.

Same shape as the result above.

projection=feed

The product reduced to what a shopping channel puts in a listing: identity, title, description, handle, brand, category path, the primary image, and per sku its code, price (with the promotional and compare-at prices), status, name, GTIN and its own image. It is the same published set and the same page as full — about a fifth of the bytes — for a caller that walks the whole catalog to EMIT a document (a product feed, a marketplace export). Everything a listing never prints is gone: options, rich content, sku metadata and option values.

{
  "additionalProperties": false,
  "properties": {
    "brand_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "categories": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "category_id": {
            "type": "string"
          },
          "is_primary": {
            "type": "boolean"
          },
          "path": {
            "type": "string"
          }
        },
        "required": [
          "category_id",
          "path",
          "is_primary"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "handle": {
      "type": "string"
    },
    "media": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "kind"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "metadata": {},
    "product_id": {
      "type": "string"
    },
    "skus": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "amount": {
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "type": "integer"
          },
          "code": {
            "type": "string"
          },
          "compare_at_amount": {
            "anyOf": [
              {
                "maximum": 9007199254740991,
                "minimum": -9007199254740991,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "currency": {
            "type": "string"
          },
          "ean": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string"
          },
          "media": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "kind": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "kind"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "promotional_price": {
            "additionalProperties": false,
            "properties": {
              "promotional_amount": {
                "maximum": 9007199254740991,
                "minimum": -9007199254740991,
                "type": "integer"
              },
              "unit_amount": {
                "maximum": 9007199254740991,
                "minimum": -9007199254740991,
                "type": "integer"
              }
            },
            "required": [
              "unit_amount",
              "promotional_amount"
            ],
            "type": "object"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "code",
          "amount",
          "currency",
          "status",
          "name",
          "ean",
          "compare_at_amount",
          "media"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "status": {
      "type": "string"
    },
    "title": {
      "type": "string"
    }
  },
  "required": [
    "product_id",
    "title",
    "description",
    "handle",
    "status",
    "metadata",
    "brand_id",
    "categories",
    "media",
    "skus"
  ],
  "type": "object"
}

Errors

validation_failed (400) · not_found (404) · unknown_projection (400)