Skip to main content
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
Performs a hybrid search (keyword + semantic) across the store’s product catalog.

​
Request body

FieldTypeRequiredDescription
querystringYesSearch query text
languagestringNoLanguage code (e.g. en, pl). Auto-detected if omitted
currencystringNoCurrency code (e.g. PLN, USD). Auto-detected if omitted
limitintegerNoResults per page (1–100, default: 24)
pageintegerNoPage number (default: 1)
ai_searchbooleanNoEnable AI-enhanced search (counts toward AI usage)
filtersobjectNoDynamic filter values (e.g. {"attribute_color": ["black"]})
include_facetsbooleanNoReturn facet counts for filters
session_idstringNoWidget 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
Sends a natural-language query to the AI assistant. Returns a streaming response (Server-Sent Events).

​
Request body

FieldTypeRequiredDescription
querystringYesNatural-language question
languagestringNoLanguage code
currencystringNoCurrency code
session_idstringNoWidget session ID

​
Headers

HeaderDescription
OriginYour store domain (required)
X-Widget-Session-IDWidget session ID
X-Ai-Session-IDAI 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.