# List products

Retrieves a paginated list of products with optional filtering and hydration.

Endpoint: GET /v1/products
Version: 1.0.0
Security: Bearer

## Query parameters:

  - `uuids[eq]` (array)
    Filter by one or more UUIDs. Accepts multiple values.

  - `familyUuids[eq]` (array)
    Filter by one or more family UUIDs. Accepts multiple values.

  - `skuUuids[eq]` (array)
    Filter by one or more SKU UUIDs. Accepts multiple values.

  - `brandUuids[eq]` (array)
    Filter by one or more brand UUIDs. Accepts multiple values.

  - `assetUuids[eq]` (array)
    Filter by one or more linked asset UUIDs. Accepts multiple values.

  - `attributeUuids[eq]` (array)
    Filter by one or more linked attribute UUIDs. Accepts multiple values.

  - `parentUuids[eq]` (array)
    Filter by one or more parent product UUIDs. Accepts multiple values.

  - `codes[eq]` (array)
    Filter by one or more exact codes. Accepts multiple values.

  - `code[contains]` (string)
    Filter by partial code match.

  - `code[starts]` (string)
    Filter by code prefix.

  - `code[ends]` (string)
    Filter by code suffix.

  - `code[order]` (string)
    Sort order for code field. Values: asc, desc.

  - `statuses[eq]` (array)
    Filter by one or more statuses. Accepts multiple values.
    Enum: "draft", "published", "unpublished", "archived", "removed"

  - `status[order]` (string)
    Sort order for status field. Values: asc, desc.

  - `types[eq]` (array)
    Filter by one or more product types. Accepts multiple values.
    Enum: "simple", "variantParent", "variant"

  - `type[order]` (string)
    Sort order for type field. Values: asc, desc.

  - `createdAt[eq]` (string)
    Filter by exact creation timestamp.
    Example: "2025-11-23T14:15:22.123456Z"

  - `createdAt[min]` (string)
    Filter by minimum creation timestamp.
    Example: "2025-11-23T14:15:22.123456Z"

  - `createdAt[max]` (string)
    Filter by maximum creation timestamp.
    Example: "2025-11-23T14:15:22.123456Z"

  - `createdAt[order]` (string)
    Sort order for creation timestamp. Values: asc, desc.

  - `updatedAt[eq]` (string)
    Filter by exact update timestamp.
    Example: "2025-11-23T14:15:22.123456Z"

  - `updatedAt[min]` (string)
    Filter by minimum update timestamp.
    Example: "2025-11-23T14:15:22.123456Z"

  - `updatedAt[max]` (string)
    Filter by maximum update timestamp.
    Example: "2025-11-23T14:15:22.123456Z"

  - `updatedAt[order]` (string)
    Sort order for update timestamp. Values: asc, desc.

  - `isArchived[eq]` (boolean)
    Filter by archived status. Values: true, false.

  - `isRemoved[eq]` (boolean)
    Filter by removed status. Values: true, false.

  - `page` (integer)
    Page number for pagination. Default is 1.

  - `size` (integer)
    Page size for pagination. Default is 20.

  - `include[productAssets]` (boolean)
    Include product asset junction UUIDs. Values: true, false.

  - `expand[productAssets]` (boolean)
    Expand product asset junctions with full details. Values: true, false.

  - `include[productAttributes]` (boolean)
    Include product attribute junction UUIDs. Values: true, false.

  - `expand[productAttributes]` (boolean)
    Expand product attribute junctions with full details. Values: true, false.

  - `include[productAttributeTerms]` (boolean)
    Include product attribute term junction UUIDs. Values: true, false.

  - `expand[productAttributeTerms]` (boolean)
    Expand product attribute term junctions with full details. Values: true, false.

  - `include[productCategories]` (boolean)
    Include product category junction UUIDs. Values: true, false.

  - `expand[productCategories]` (boolean)
    Expand product category junctions with full details. Values: true, false.

  - `include[productTags]` (boolean)
    Include product tag junction UUIDs. Values: true, false.

  - `expand[productTags]` (boolean)
    Expand product tag junctions with full details. Values: true, false.

  - `include[contents]` (boolean)
    Include content UUIDs. Values: true, false.

  - `expand[contents]` (boolean)
    Expand localized content with full details. Values: true, false.

  - `include[metadata]` (boolean)
    Include metadata UUIDs. Values: true, false.

  - `expand[metadata]` (boolean)
    Expand metadata with full details. Values: true, false.

  - `include[relations]` (boolean)
    Include relation UUIDs. Values: true, false.

  - `expand[relations]` (boolean)
    Expand product relations with full details. Values: true, false.

  - `expand[completeness]` (boolean)
    Expand completeness data with dimension scores and issues. Values: true, false.

## Response 200 fields (application/json):

  - `items` (array, required)

  - `items.uuid` (string, required)
    Unique identifier for this product.

  - `items.familyUuid` (string,null)
    Identifier of the family defining structure and requirements for this product.

  - `items.skuUuid` (string,null)
    Identifier of the SKU providing inventory and dimensional data.

  - `items.parentUuid` (string,null)
    Identifier of the parent product for variant relationships.

  - `items.brandUuid` (string,null)
    Identifier of the brand associated with this product.

  - `items.createdAt` (string, required)
    Timestamp when this product was created.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.updatedAt` (string, required)
    Timestamp when this product was last modified.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.removedAt` (string,null)
    Timestamp when this product was removed. Null if not removed.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.archivedAt` (string,null)
    Timestamp when this product was archived. Null if not archived.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.status` (string, required)
    Current lifecycle status of this product.
    Enum: "draft", "published", "unpublished", "archived", "removed"

  - `items.type` (string, required)
    Product type defining variant behavior.
    Enum: "simple", "variantParent", "variant"

  - `items.code` (string, required)
    Unique code identifier for this product.

  - `items.overallScore` (integer, required)
    Completeness score from 0-100 indicating how complete this product is.

  - `items.canPublish` (boolean, required)
    Whether this product meets all required criteria for publishing.

  - `items.productAssetUuids` (array,null)
    Collection of product-asset junction UUIDs. Populated when include[productAssets]=true.

  - `items.productAssets` (array,null)
    Collection of product-asset junctions. Populated when expand[productAssets]=true.

  - `items.productAssets.uuid` (string, required)
    Unique identifier for this product-asset association.

  - `items.productAssets.productUuid` (string, required)
    Identifier of the product this asset is linked to.

  - `items.productAssets.assetUuid` (string, required)
    Identifier of the linked asset.

  - `items.productAssets.productAssetTypeUuid` (string, required)
    Identifier of the product asset type.

  - `items.productAssets.createdAt` (string, required)
    Timestamp when this association was created.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.productAssets.updatedAt` (string, required)
    Timestamp when this association was last modified.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.productAssets.order` (integer, required)
    Display order for this asset in product galleries.

  - `items.productAttributeUuids` (array,null)
    Collection of product-attribute junction UUIDs. Populated when include[productAttributes]=true.

  - `items.productAttributes` (array,null)
    Collection of product-attribute junctions. Populated when expand[productAttributes]=true.

  - `items.productAttributes.uuid` (string, required)
    Unique identifier for this product-attribute association.

  - `items.productAttributes.productUuid` (string, required)
    Identifier of the product this attribute is linked to.

  - `items.productAttributes.attributeUuid` (string, required)
    Identifier of the linked attribute.

  - `items.productAttributes.isVariant` (boolean, required)
    Whether this attribute is used to define product variants.

  - `items.productAttributeTermUuids` (array,null)
    Collection of product-term junction UUIDs. Populated when include[productAttributeTerms]=true.

  - `items.productAttributeTerms` (array,null)
    Collection of product-term junctions. Populated when expand[productAttributeTerms]=true.

  - `items.productAttributeTerms.uuid` (string, required)
    Unique identifier for this product-term association.

  - `items.productAttributeTerms.productUuid` (string, required)
    Identifier of the product this term is linked to.

  - `items.productAttributeTerms.productAttributeUuid` (string, required)
    Identifier of the product attribute.

  - `items.productAttributeTerms.attributeTermUuid` (string, required)
    Identifier of the linked attribute term.

  - `items.productCategoryUuids` (array,null)
    Collection of product-category junction UUIDs. Populated when include[productCategories]=true.

  - `items.productCategories` (array,null)
    Collection of product-category junctions. Populated when expand[productCategories]=true.

  - `items.productCategories.uuid` (string, required)
    Unique identifier for this product-category association.

  - `items.productCategories.productUuid` (string, required)
    Identifier of the product this category is linked to.

  - `items.productCategories.categoryUuid` (string, required)
    Identifier of the linked category.

  - `items.productTagUuids` (array,null)
    Collection of product-tag junction UUIDs. Populated when include[productTags]=true.

  - `items.productTags` (array,null)
    Collection of product-tag junctions. Populated when expand[productTags]=true.

  - `items.productTags.uuid` (string, required)
    Unique identifier for this product-tag association.

  - `items.productTags.productUuid` (string, required)
    Identifier of the product this tag is linked to.

  - `items.productTags.tagUuid` (string, required)
    Identifier of the linked tag.

  - `items.contentUuids` (array,null)
    Collection of content UUIDs for this product.

  - `items.contents` (array,null)
    Collection of localized content for this product.

  - `items.contents.uuid` (string, required)
    Unique identifier for this content entry.

  - `items.contents.productUuid` (string, required)
    Identifier of the product this content belongs to.

  - `items.contents.localeUuid` (string, required)
    Identifier of the locale for this content.

  - `items.contents.createdAt` (string, required)
    Timestamp when this content was created.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.contents.updatedAt` (string, required)
    Timestamp when this content was last modified.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.contents.label` (string, required)
    Localized display label for the product.

  - `items.contents.description` (string,null)
    Localized detailed description for the product.

  - `items.contents.shortDescription` (string,null)
    Localized short description for the product.

  - `items.metadataUuids` (array,null)
    Collection of metadata UUIDs for this product.

  - `items.metadata` (array,null)
    Collection of custom metadata entries for this product.

  - `items.metadata.uuid` (string, required)
    Unique identifier for this metadata entry.

  - `items.metadata.productUuid` (string, required)
    Identifier of the product this metadata belongs to.

  - `items.metadata.localeUuid` (string, required)
    Identifier of the locale this metadata is associated with.

  - `items.metadata.createdAt` (string, required)
    Timestamp when this metadata entry was created.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.metadata.updatedAt` (string, required)
    Timestamp when this metadata entry was last modified.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.metadata.type` (string, required)
    Data type of the metadata value.
    Enum: "string", "number", "boolean", "json"

  - `items.metadata.key` (string, required)
    Metadata key identifier.

  - `items.metadata.value` (string, required)
    Metadata value content.

  - `items.relationUuids` (array,null)
    Collection of relation UUIDs for this product.

  - `items.relations` (array,null)
    Collection of related products.

  - `items.relations.uuid` (string, required)
    Unique identifier for this product relation.

  - `items.relations.productUuid` (string, required)
    Identifier of the source product owning this relation.

  - `items.relations.productReferenceUuid` (string, required)
    Identifier of the target product being referenced.

  - `items.relations.createdAt` (string, required)
    Timestamp when this relation was created.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.relations.updatedAt` (string, required)
    Timestamp when this relation was last modified.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.relations.productRelationTypeUuid` (string, required)
    Identifier of the product relation type.

  - `items.completeness` (object,null)
    Completeness evaluation data for a product.

  - `items.completeness.uuid` (string, required)
    Unique identifier for this completeness record.

  - `items.completeness.productUuid` (string, required)
    Identifier of the product this completeness belongs to.

  - `items.completeness.createdAt` (string, required)
    Timestamp when this completeness record was created.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.completeness.updatedAt` (string, required)
    Timestamp when this completeness record was last evaluated.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.completeness.overallScore` (integer, required)
    Overall completeness score from 0-100.

  - `items.completeness.canPublish` (boolean, required)
    Whether the product meets all required criteria for publishing.

  - `items.completeness.dimensionScores` (array,null)
    Collection of completeness scores broken down by dimension.

  - `items.completeness.dimensionScores.uuid` (string, required)
    Unique identifier for this dimension score.

  - `items.completeness.dimensionScores.productUuid` (string, required)
    Identifier of the product this score belongs to.

  - `items.completeness.dimensionScores.productCompletenessUuid` (string, required)
    Identifier of the parent completeness record.

  - `items.completeness.dimensionScores.createdAt` (string, required)
    Timestamp when this dimension score was created.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.completeness.dimensionScores.updatedAt` (string, required)
    Timestamp when this dimension score was last updated.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.completeness.dimensionScores.dimension` (string, required)
    The dimension being evaluated (Attributes, Categories, Assets, Relations, Sku).
    Enum: "attributes", "categories", "assets", "relations", "sku"

  - `items.completeness.dimensionScores.score` (integer, required)
    Completeness score for this dimension from 0-100.

  - `items.completeness.dimensionScores.totalRequiredCount` (integer, required)
    Total number of required items in this dimension.

  - `items.completeness.dimensionScores.totalOptionalCount` (integer, required)
    Total number of optional items in this dimension.

  - `items.completeness.dimensionScores.requiredSatisfiedCount` (integer, required)
    Number of required items that are satisfied.

  - `items.completeness.dimensionScores.requiredUnsatisfiedCount` (integer, required)
    Number of required items that are not satisfied.

  - `items.completeness.dimensionScores.optionalSatisfiedCount` (integer, required)
    Number of optional items that are satisfied.

  - `items.completeness.dimensionScores.optionalUnsatisfiedCount` (integer, required)
    Number of optional items that are not satisfied.

  - `items.completeness.dimensionScores.issues` (array,null)
    Collection of issues preventing full completeness in this dimension.

  - `items.completeness.dimensionScores.issues.uuid` (string, required)
    Unique identifier for this issue.

  - `items.completeness.dimensionScores.issues.productUuid` (string, required)
    Identifier of the product this issue belongs to.

  - `items.completeness.dimensionScores.issues.dimensionScoreUuid` (string, required)
    Identifier of the parent dimension score.

  - `items.completeness.dimensionScores.issues.itemUuid` (string,null)
    Identifier of the specific item causing the issue.

  - `items.completeness.dimensionScores.issues.createdAt` (string, required)
    Timestamp when this issue was identified.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.completeness.dimensionScores.issues.updatedAt` (string, required)
    Timestamp when this issue was last updated.
    Example: "2025-11-23T14:15:22.123456Z"

  - `items.completeness.dimensionScores.issues.type` (string, required)
    Type of issue (Missing, BelowMinimum, AboveMaximum, Forbidden, InvalidState).
    Enum: "missing", "belowMinimum", "aboveMaximum", "forbidden", "invalidState"

  - `items.completeness.dimensionScores.issues.itemType` (string, required)
    Type of item causing the issue (e.g., Attribute, Category).

  - `items.completeness.dimensionScores.issues.code` (string, required)
    Code of the item causing the issue.

  - `items.completeness.dimensionScores.issues.message` (string, required)
    Human-readable message describing the issue.

  - `items.completeness.dimensionScores.issues.isRequired` (boolean, required)
    Whether the issue is for a required item.

  - `pagination` (object, required)

  - `pagination.page` (integer, required)

  - `pagination.size` (integer, required)

  - `pagination.totalItems` (integer, required)

  - `pagination.totalPages` (integer, required)

## Response 401 fields (application/problem+json):

  - `type` (string,null)

  - `title` (string,null)

  - `status` (integer,null)

  - `detail` (string,null)

  - `instance` (string,null)

## Response 403 fields (application/problem+json):

  - `type` (string,null)

  - `title` (string,null)

  - `status` (integer,null)

  - `detail` (string,null)

  - `instance` (string,null)

  - `correlationId` (string,null)

## Response 500 fields (application/problem+json):

  - `type` (string,null)

  - `title` (string,null)

  - `status` (integer,null)

  - `detail` (string,null)

  - `instance` (string,null)

  - `correlationId` (string,null)