Reference
Catalogue
Your products, their variants and their stock, so the assistant answers from them. A test key works on its own test catalogue; the assistant reads the live one.
Laufkontor Brandt is a sample shop. The examples show sample data.
List products
GET /v1/products
A secret key with the catalogue:write scope. See scopes.
Your products in this mode, by id, a page at a time: at most limit products and at most 2 MB, so a page of large products ends early, with a next_cursor for the rest.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
limit | integer, in the query | Optional | At most this many products (1 to 50; default 20). A page also ends early, with a next_cursor, once it holds 2 MB of products. |
cursor | string, in the query | Optional | The next_cursor of the page before. |
Answers
| Status | When |
|---|---|
200 | A page of products. |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
422 | The body or the query does not match the schema. details names each field and the rule it broke, at most 10, never its value; never a name you chose either (an unknown property is named by its parent, an unknown query parameter as query, and a step of a field's path that is no name of the spec is *). More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/products' \
-H "Authorization: Bearer $UNCART_KEY"
{
"data": [
{
"id": "trail-schuh-1",
"title": "Trailschuh Kante",
"url": "https://shop.example.com/products/trail-schuh-1",
"status": "active",
"currency": "EUR",
"description": "Leichter Trailschuh mit griffiger Sohle.",
"product_type": "Laufschuhe",
"vendor": "Laufkontor Brandt",
"tags": [
"trail",
"leicht"
],
"collections": [
{
"id": "trail",
"title": "Trail"
}
],
"image_url": "https://shop.example.com/images/trail-schuh-1.jpg",
"options": [
{
"name": "Größe",
"values": [
"42",
"43"
]
}
],
"variants": [
{
"id": "trail-schuh-1-42",
"title": "42",
"options": [
{
"name": "Größe",
"value": "42"
}
],
"price": "129.90",
"available": 4
},
{
"id": "trail-schuh-1-43",
"title": "43",
"options": [
{
"name": "Größe",
"value": "43"
}
],
"price": "129.90",
"available": 0
}
],
"updated_at": "2026-10-26T08:00:00.000Z"
}
],
"next_cursor": null
}
Get a product
GET /v1/products/{product_id}
A secret key with the catalogue:write scope. See scopes.
The product as Uncart holds it in this mode.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
product_id | string, in the path | Required |
Answers
| Status | When |
|---|---|
200 | The product. |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
404 | The shop has no product with this id in this mode. |
422 | The body or the query does not match the schema. details names each field and the rule it broke, at most 10, never its value; never a name you chose either (an unknown property is named by its parent, an unknown query parameter as query, and a step of a field's path that is no name of the spec is *). More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/products/no-such-product' \
-H "Authorization: Bearer $UNCART_KEY"
{
"error": "not_found",
"message": "No product with this id.",
"request_id": "req_00000000000000000000000000000000"
}
curl 'https://api.uncart.ai/v1/products/trail-schuh-2' \
-H "Authorization: Bearer $UNCART_KEY"
curl 'https://api.uncart.ai/v1/products/trail-schuh-2' \
-H "Authorization: Bearer $UNCART_KEY"
curl 'https://api.uncart.ai/v1/products/no-such-product' \
-H "Authorization: Bearer $UNCART_KEY"
{
"id": "trail-schuh-1",
"title": "Trailschuh Kante",
"url": "https://shop.example.com/products/trail-schuh-1",
"status": "active",
"currency": "EUR",
"description": "Leichter Trailschuh mit griffiger Sohle.",
"product_type": "Laufschuhe",
"vendor": "Laufkontor Brandt",
"tags": [
"trail",
"leicht"
],
"collections": [
{
"id": "trail",
"title": "Trail"
}
],
"image_url": "https://shop.example.com/images/trail-schuh-1.jpg",
"options": [
{
"name": "Größe",
"values": [
"42",
"43"
]
}
],
"variants": [
{
"id": "trail-schuh-1-42",
"title": "42",
"options": [
{
"name": "Größe",
"value": "42"
}
],
"price": "129.90",
"available": 4
},
{
"id": "trail-schuh-1-43",
"title": "43",
"options": [
{
"name": "Größe",
"value": "43"
}
],
"price": "129.90",
"available": 0
}
],
"updated_at": "2026-10-26T08:00:00.000Z"
}
Create or replace a product
PUT /v1/products/{product_id}
A secret key with the catalogue:write scope. See scopes.
Creates the product, or replaces it whole: its variants are exactly those you send (variants you leave out are gone). Its page must be on a domain you verified; each price exact in its currency. A variant id belongs to one product: naming one that another product holds is 409 conflict (move it by putting the other product without it first). A product may take at most 100,000 bytes as Uncart keeps it (its JSON without the shop and time; a larger one is 422 naming too_large): a real product needs far less. Each catalogue, per mode, holds at most 100,000 products and 1 GB live, 1,000 products and 25 MB in test mode (x-uncart-limits); a new product past either is 409 conflict naming catalogue_products or catalogue_bytes in details, and nothing changes. A test catalogue is free and kept 30 days after its last change (the product, or its stock); live products stay until you delete them. Writes are last-writer-wins: a stock update sent while a put of the same product runs is applied after it.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
product_id | string, in the path | Required | |
Idempotency-Key | string, in the header | Optional | A value you choose (a UUID) that makes this write safe to send again: for 24 hours the same key answers the first answer and does nothing twice. 1 to 255 visible ASCII characters. Required on every POST. |
Request body
| Field | Type | Required | What it is |
|---|---|---|---|
title | string | Required | |
url | string | Required | The product's page: https, on a domain you verified (exactly that host), within Uncart's link rules (allowed query parameters only, no fragment). Uncart checks it when it arrives and again before every use. |
status | string: "active", "draft" | Required | active: on sale, the assistant may talk about it. draft: kept, never offered. |
currency | string | Required | An ISO 4217 currency code (EUR), only one that names money: never a precious metal, drawing right, bond-market unit, the testing code or "no currency" (XAU, XAG, XPT, XPD, XDR, XBA to XBD, XSU, XUA, XTS, XXX), and never a code ISO 4217 does not list. |
description | string | Optional | Your words about the product (plain text or HTML). The assistant reads it as data, at most 1,500 characters of its text. |
product_type | string | Optional | |
vendor | string | Optional | |
tags | array of string | Optional | |
collections | array of object | Optional | |
collections[].id | string | Required | |
collections[].title | string | Required | |
image_url | string | Optional | Its main photo: https on a public host name. |
options | array of object | Optional | |
options[].name | string | Required | |
options[].values | array of string | Required | |
variants | array of object | Required | |
variants[].id | string | Required | Your own id of the variant: 1 to 64 letters, digits, - and _, once per shop and mode. |
variants[].title | string | Required | |
variants[].options | array of object | Optional | |
variants[].options[].name | string | Required | |
variants[].options[].value | string | Required | |
variants[].price | string | Required | A decimal amount in the product's currency, exact: at most as many decimals as the currency has (EUR 2, JPY 0, KWD 3). Never rounded: more decimals are refused. |
variants[].available | integer | Required | Units a shopper can buy now. Send changes as they happen (POST /inventory). |
Answers
| Status | When |
|---|---|
200 | The product as Uncart now holds it. |
400 | The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
404 | Nothing is at this address, or the shop has no such object. More |
409 | A variant id this product names belongs to another product of the shop, the catalogue holds the most products or bytes it may (details names which: catalogue_products, catalogue_bytes), or a request with this Idempotency-Key is still being handled. |
413 | The body is over 1 MB. More |
415 | A body was sent that is not application/json. More |
422 | The body or the query breaks the schema or Uncart's rules (details names each field and rule, never a value), or this Idempotency-Key was used for another request. More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/products/no-such-product' \
-X PUT \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"title": "Trailschuh Kante",
"url": "https://shop.example.com/products/trail-schuh-1",
"status": "active",
"currency": "EUR",
"description": "Leichter Trailschuh mit griffiger Sohle.",
"product_type": "Laufschuhe",
"vendor": "Laufkontor Brandt",
"tags": [
"trail",
"leicht"
],
"collections": [
{
"id": "trail",
"title": "Trail"
}
],
"image_url": "https://shop.example.com/images/trail-schuh-1.jpg",
"options": [
{
"name": "Größe",
"values": [
"42",
"43"
]
}
],
"variants": [
{
"id": "trail-schuh-1-42",
"title": "42",
"options": [
{
"name": "Größe",
"value": "42"
}
],
"price": "129.90",
"available": 4
},
{
"id": "trail-schuh-1-43",
"title": "43",
"options": [
{
"name": "Größe",
"value": "43"
}
],
"price": "129.90",
"available": 0
}
]
}'
{
"id": "trail-schuh-1",
"title": "Trailschuh Kante",
"url": "https://shop.example.com/products/trail-schuh-1",
"status": "active",
"currency": "EUR",
"description": "Leichter Trailschuh mit griffiger Sohle.",
"product_type": "Laufschuhe",
"vendor": "Laufkontor Brandt",
"tags": [
"trail",
"leicht"
],
"collections": [
{
"id": "trail",
"title": "Trail"
}
],
"image_url": "https://shop.example.com/images/trail-schuh-1.jpg",
"options": [
{
"name": "Größe",
"values": [
"42",
"43"
]
}
],
"variants": [
{
"id": "trail-schuh-1-42",
"title": "42",
"options": [
{
"name": "Größe",
"value": "42"
}
],
"price": "129.90",
"available": 4
},
{
"id": "trail-schuh-1-43",
"title": "43",
"options": [
{
"name": "Größe",
"value": "43"
}
],
"price": "129.90",
"available": 0
}
],
"updated_at": "2026-10-27T09:00:00.000Z"
}
curl 'https://api.uncart.ai/v1/products/trail-schuh-2' \
-X PUT \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"title": "Trailschuh Kante GTX",
"url": "https://shop.example.com/products/trail-schuh-2",
"status": "active",
"currency": "EUR",
"description": "Leichter Trailschuh mit griffiger Sohle.",
"product_type": "Laufschuhe",
"vendor": "Laufkontor Brandt",
"tags": [
"trail",
"leicht"
],
"collections": [
{
"id": "trail",
"title": "Trail"
}
],
"image_url": "https://shop.example.com/images/trail-schuh-1.jpg",
"options": [
{
"name": "Größe",
"values": [
"42",
"43"
]
}
],
"variants": [
{
"id": "trail-schuh-2-42",
"title": "42",
"options": [
{
"name": "Größe",
"value": "42"
}
],
"price": "149.9",
"available": 2
}
]
}'
{
"id": "trail-schuh-2",
"title": "Trailschuh Kante GTX",
"url": "https://shop.example.com/products/trail-schuh-2",
"status": "active",
"currency": "EUR",
"description": "Leichter Trailschuh mit griffiger Sohle.",
"product_type": "Laufschuhe",
"vendor": "Laufkontor Brandt",
"tags": [
"trail",
"leicht"
],
"collections": [
{
"id": "trail",
"title": "Trail"
}
],
"image_url": "https://shop.example.com/images/trail-schuh-1.jpg",
"options": [
{
"name": "Größe",
"values": [
"42",
"43"
]
}
],
"variants": [
{
"id": "trail-schuh-2-42",
"title": "42",
"options": [
{
"name": "Größe",
"value": "42"
}
],
"price": "149.90",
"available": 2
}
],
"updated_at": "2026-10-27T09:00:00.000Z"
}
curl 'https://api.uncart.ai/v1/products/trail-schuh-2' \
-X PUT \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"title": "Trailschuh Kante GTX",
"url": "https://shop.example.com/products/trail-schuh-2",
"status": "active",
"currency": "EUR",
"description": "Leichter Trailschuh mit griffiger Sohle.",
"product_type": "Laufschuhe",
"vendor": "Laufkontor Brandt",
"tags": [
"trail",
"leicht"
],
"collections": [
{
"id": "trail",
"title": "Trail"
}
],
"image_url": "https://shop.example.com/images/trail-schuh-1.jpg",
"options": [
{
"name": "Größe",
"values": [
"42",
"43"
]
}
],
"variants": [
{
"id": "trail-schuh-1-42",
"title": "42",
"price": "149.90",
"available": 1
}
]
}'
{
"error": "conflict",
"message": "A variant id of this product belongs to another product.",
"request_id": "req_00000000000000000000000000000000"
}
curl 'https://api.uncart.ai/v1/products/no-such-product' \
-X PUT \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"title": "Trailschuh Kante",
"url": "https://shop.example.com/products/trail-schuh-1",
"status": "active",
"currency": "EUR",
"description": "Leichter Trailschuh mit griffiger Sohle.",
"product_type": "Laufschuhe",
"vendor": "Laufkontor Brandt",
"tags": [
"trail",
"leicht"
],
"collections": [
{
"id": "trail",
"title": "Trail"
}
],
"image_url": "https://shop.example.com/images/trail-schuh-1.jpg",
"options": [
{
"name": "Größe",
"values": [
"42",
"43"
]
}
],
"variants": [
{
"id": "trail-schuh-1-42",
"title": "42",
"options": [
{
"name": "Größe",
"value": "42"
}
],
"price": "129.90",
"available": 4
},
{
"id": "trail-schuh-1-43",
"title": "43",
"options": [
{
"name": "Größe",
"value": "43"
}
],
"price": "129.90",
"available": 0
}
]
}'
curl 'https://api.uncart.ai/v1/products/no-such-product' \
-X PUT \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"title": "Trailschuh Kante",
"url": "https://shop.example.com/products/trail-schuh-1",
"status": "active",
"currency": "EUR",
"description": "Leichter Trailschuh mit griffiger Sohle.",
"product_type": "Laufschuhe",
"vendor": "Laufkontor Brandt",
"tags": [
"trail",
"leicht"
],
"collections": [
{
"id": "trail",
"title": "Trail"
}
],
"image_url": "https://shop.example.com/images/trail-schuh-1.jpg",
"options": [
{
"name": "Größe",
"values": [
"42",
"43"
]
}
],
"variants": [
{
"id": "trail-schuh-1-42",
"title": "42",
"options": [
{
"name": "Größe",
"value": "42"
}
],
"price": "129.90",
"available": 4
},
{
"id": "trail-schuh-1-43",
"title": "43",
"options": [
{
"name": "Größe",
"value": "43"
}
],
"price": "129.90",
"available": 0
}
]
}'
{
"error": "idempotency_in_progress",
"message": "A request with this Idempotency-Key is still in progress.",
"request_id": "req_00000000000000000000000000000000"
}
Delete a product
DELETE /v1/products/{product_id}
A secret key with the catalogue:write scope. See scopes.
Removes the product and its variants. The assistant stops talking about it at once.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
product_id | string, in the path | Required | |
Idempotency-Key | string, in the header | Optional | A value you choose (a UUID) that makes this write safe to send again: for 24 hours the same key answers the first answer and does nothing twice. 1 to 255 visible ASCII characters. Required on every POST. |
Answers
| Status | When |
|---|---|
200 | Deleted. |
400 | The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
404 | The shop has no product with this id in this mode. |
409 | A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More |
413 | The body is over 1 MB. More |
422 | The body or the query breaks the schema or Uncart's rules (details names each field and rule, never a value), or this Idempotency-Key was used for another request. More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/products/no-such-product' \
-X DELETE \
-H "Authorization: Bearer $UNCART_KEY"
{
"error": "not_found",
"message": "No product with this id.",
"request_id": "req_00000000000000000000000000000000"
}
curl 'https://api.uncart.ai/v1/products/trail-schuh-2' \
-X DELETE \
-H "Authorization: Bearer $UNCART_KEY"
curl 'https://api.uncart.ai/v1/products/trail-schuh-2' \
-X DELETE \
-H "Authorization: Bearer $UNCART_KEY"
curl 'https://api.uncart.ai/v1/products/no-such-product' \
-X DELETE \
-H "Authorization: Bearer $UNCART_KEY"
{
"id": "trail-schuh-1",
"deleted": true
}
Set stock
POST /v1/inventory
A secret key with the catalogue:write scope. See scopes.
Sets how many units of each variant a shopper can buy now (up to 100 variants at once). Send it whenever stock changes; the assistant states stock from it. Variants Uncart does not hold are named back in unknown, nothing else changes for them.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
Idempotency-Key | string, in the header | Optional | A value you choose (a UUID) that makes this write safe to send again: for 24 hours the same key answers the first answer and does nothing twice. 1 to 255 visible ASCII characters. Required on every POST. |
Request body
| Field | Type | Required | What it is |
|---|---|---|---|
items | array of object | Required | |
items[].variant_id | string | Required | Your own id of the variant: 1 to 64 letters, digits, - and _, once per shop and mode. |
items[].available | integer | Required |
Answers
| Status | When |
|---|---|
200 | What was set, and what Uncart does not hold. |
400 | The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
409 | A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More |
413 | The body is over 1 MB. More |
415 | A body was sent that is not application/json. More |
422 | The body or the query breaks the schema or Uncart's rules (details names each field and rule, never a value), or this Idempotency-Key was used for another request. More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/inventory' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"items": [
{
"variant_id": "trail-schuh-1-43",
"available": 6
},
{
"variant_id": "gibt-es-nicht",
"available": 1
}
]
}'
{
"updated": [
"trail-schuh-1-43"
],
"unknown": [
"gibt-es-nicht"
]
}