Documentation Index
Fetch the complete documentation index at: https://docs.cartally.co/llms.txt
Use this file to discover all available pages before exploring further.
The Cartally widget communicates with the Cartally proxy API. These endpoints are called automatically by the widget — you do not need to call them yourself unless building a custom frontend.
Search endpoint
POST https://app.cartally.co/api/search
Request body
| Field | Type | Required | Description |
|---|
query | string | Yes | Search query text |
language | string | No | Language code (e.g. en, pl). Auto-detected if omitted |
currency | string | No | Currency code (e.g. PLN, USD). Auto-detected if omitted |
limit | integer | No | Results per page (1–100, default: 24) |
page | integer | No | Page number (default: 1) |
ai_search | boolean | No | Enable AI-enhanced search (counts toward AI usage) |
filters | object | No | Dynamic filter values (e.g. {"attribute_color": ["black"]}) |
include_facets | boolean | No | Return facet counts for filters |
session_id | string | No | Widget session ID |
Response
{
"products": [
{
"id": "12345-black",
"product_id": "12345",
"product_name": "Mountain Bike Helmet",
"product_description": "Lightweight helmet...",
"product_categories": ["Helmets", "Safety"],
"photos": ["https://myshop.com/img/helmet-black.jpg"],
"url": "https://myshop.com/product/helmet",
"price_pln": 19900,
"price_eur": 4500,
"attribute_color": ["black"]
}
],
"suggestions": ["mountain bike", "bike helmet", "road helmet"],
"questions": ["What is the lightest helmet?"],
"total_products": 42,
"facets": { ... },
"attribute_labels": { "attribute_color": "Color" },
"color_hex_map": { "black": "#000000" }
}
Authentication
The widget authenticates automatically via the Origin header. The proxy verifies that the requesting domain matches a registered shop.
A session token (JWT) is returned in the response headers on the first request and must be sent back in subsequent requests.
AI Chat endpoint
POST https://app.cartally.co/api/ai/chat
Request body
| Field | Type | Required | Description |
|---|
query | string | Yes | Natural-language question |
language | string | No | Language code |
currency | string | No | Currency code |
session_id | string | No | Widget session ID |
| Header | Description |
|---|
Origin | Your store domain (required) |
X-Widget-Session-ID | Widget session ID |
X-Ai-Session-ID | AI conversation session ID (for follow-up questions) |
Response
The response is streamed as Server-Sent Events (SSE). Each event contains a chunk of the AI response with product references.
Usage limits
AI chat requests count toward your plan’s AI request limit. When the limit is reached, the endpoint returns HTTP 403.
Rate limits
Both endpoints are rate-limited per session token and per IP address. The widget handles rate limiting automatically with appropriate error messages.