Skip to content
Semantico Docs

List products

GET
/products/
curl --request GET \
  --url 'https://api.semantico.ai/api/v1/products/?locale=en-US&sections=short_description%2Ccolour&tasks=none&sorting=asc&order_by=date&page=1&page_size=20' \
  --header 'Authorization: Bearer <token>'

Returns a paginated list of parent and standalone products. Variants are exposed under /products/{id}/variants/.

Custom sections are not included by default. Pass sections with the section codes you need and each product gets a sections object keyed by code, e.g. ?sections=short_description,colour. See Custom sections in the product list.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
locale
string
Example
en-US

Locale for name, description, and attributes. Defaults to the workspace default locale.

search
string

Matches barcode, sku, mpn, asin, and name.

brand
string

Substring match on a single brand.

brands
string

Filter by multiple brands (repeat or comma-separate).

category
string

Category UUID (includes descendants), or no_category.

tag
string

Tag IDs (repeatable). Use none for products without tags.

sections
string

Custom section codes to include in each product’s sections object (repeat or comma-separate). A plain code only includes the section. Adding a condition also filters the list: code:value (exact, case-insensitive), code:~value (contains), code:filled, code:empty, or code:gt:5 (also gte, lt, lte, eq).

Example
short_description,colour
created_at_after
string format: date

Only products created on or after this date (YYYY-MM-DD).

created_at_before
string format: date

Only products created on or before this date (YYYY-MM-DD).

images
boolean

Require (true) or exclude (false) products with images.

tasks
string
Allowed values: none success not_generated

Filter by generation status.

product_list
string

Filter by product list code.

sorting
string
default: desc
Allowed values: asc desc
order_by
string
default: date
Allowed values: date task
page
integer
default: 1 >= 1

Page number, starting at 1.

page_size
integer
default: 20 >= 1

Number of results per page.

Responses

Section titled “Responses”

200

Section titled “200”

Paginated products

Media typeapplication/json
object
pagination
object
links
object
next

URL of the next page, or null on the last page.

string | null format: uri
previous

URL of the previous page, or null on the first page.

string | null format: uri
total

Total number of results across all pages.

integer
page_size
integer
page
integer
results
Array<object>

Lightweight product returned by GET /products/.

object
id
integer
sku
string
barcode
string
mpn
string | null
asin
string | null
external_id
string | null
brand
string
name
string
created_at
string format: date-time
sections

Only present when the sections query parameter is sent. One key per requested section code. Text sections hold a string; single- and multiple-choice sections hold a list of selected options. A section with no content for the product is null.

object
key
additional properties
One of:
string
Example
{
  "pagination": {
    "links": {
      "next": null,
      "previous": null
    },
    "total": 1,
    "page_size": 20,
    "page": 1
  },
  "results": [
    {
      "id": 1234,
      "sku": "SKU-001",
      "name": "Acme water bottle 750ml",
      "created_at": "2026-10-01T09:30:00Z",
      "sections": {
        "short_description": "Leak-proof 750ml steel bottle that keeps drinks cold for 24h.",
        "colour": [
          {
            "id": 88,
            "reference": 12,
            "label": "Blue",
            "external_id": "blue",
            "color": "#2563EB",
            "content": "",
            "order": 0
          }
        ]
      }
    }
  ]
}

401

Section titled “401”

Missing or invalid token.

Media typeapplication/json
object
detail
string
Examplegenerated
{
  "detail": "example"
}