Developer API

A read-only API to your own shop's assistant: answers, as-you-type suggestions, similar products and the catalogue, for your own server, app or page.

API version 1.0.0

Overview#

The API gives your code what the on-site assistant gives your shoppers: a full answer to a question in plain words, product suggestions as someone types, lists of similar products, and read access to the catalogue. Base URL: https://assistant.onesite.agency/api/v1.

It is read-only and limited to one shop: a key opens the shop that created it and nothing else. Product names, prices, stock and links always come from the catalogue; the AI writes only the short texts say and why, and the response marks them (see AI-generated text below).

Requests and responses are JSON over HTTPS. The version is in the path (/v1). The API is available on plans that include the developer API.

Quick start#

From nothing to a first answer in three steps.

1. Create a key#

In the cabinet open the Developers tab, name the key and choose its scopes, then optionally an IP list and browser origins. The key is shown once and we keep only a hash, so copy it straight into your server's secrets and never into a repository. A lost key cannot be recovered: revoke it and create another.

2. Check it#

Call GET /me. A 200 shows which shop the key opens, its scopes and its limits. Replace YOUR_API_KEY with your key.

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/me' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/me", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/me",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

3. Ask a question#

Send the shopper's words to POST /answers (needs the answer scope). You get the best match, alternatives and a one-line reason for each.

Example request, curl

curl -X POST 'https://assistant.onesite.agency/api/v1/answers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 3f9d1c52-7b0e-4a53-9a6f-0c2f8e1d77aa' \
  -d '{
  "query": "a cold, quiet science fiction novel for a long winter",
  "language": "en",
  "in_stock_only": true,
  "session_id": "visitor-8841"
}'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/answers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "3f9d1c52-7b0e-4a53-9a6f-0c2f8e1d77aa",
  },
  body: JSON.stringify({
    "query": "a cold, quiet science fiction novel for a long winter",
    "language": "en",
    "in_stock_only": true,
    "session_id": "visitor-8841"
  }),
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.post(
    "https://assistant.onesite.agency/api/v1/answers",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "3f9d1c52-7b0e-4a53-9a6f-0c2f8e1d77aa",
    },
    json={
        "query": "a cold, quiet science fiction novel for a long winter",
        "language": "en",
        "in_stock_only": True,
        "session_id": "visitor-8841",
    },
)
print(response.status_code, response.json())

Authentication#

Send the key in the Authorization header as a bearer token. Never put it in the URL: URLs end up in logs and browser history.

Authentication

Authorization: Bearer YOUR_API_KEY

A missing, malformed, unknown or revoked key all give the same 401 invalid_api_key, so an answer never tells someone guessing that a key is almost right. Repeated invalid keys from one address are slowed down with 429 too_many_failed_attempts.

A key belongs to exactly one shop and cannot read another: a product id from another shop answers 404, exactly like a missing one.

You can narrow a key further with an IP allow-list (403 ip_not_allowed) and a browser-origin allow-list (403 origin_not_allowed). Scopes are fixed when the key is created; to widen them, create another key.

Scopes and limits#

Each key carries the scopes it may use. Limits apply per key and per scope.

Scopes, their endpoints and limits
Scope	Endpoints	Calls per 60 s
`answer`	`POST /answers`	20
`suggest`	`GET /suggestions`	120
`catalogue:read`	`GET /products, GET /products/{product_id}`	120
`similar`	`GET /products/{product_id}/similar`	60
`analytics:read`	`GET /analytics/summary, GET /analytics/series, GET /analytics/queries, GET /analytics/sales`	30

POST /answers also has a daily cap of 500 calls per key (UTC day), because every answer is a model call. A replay with the same Idempotency-Key does not count.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 adds Retry-After (seconds). Wait that long instead of retrying in a loop. GET /me needs a valid key but no particular scope.

Endpoints#

Every operation below is built from the OpenAPI document, and every example is run against the real API by our tests, so the samples cannot drift from the API. Descriptions of operations and fields are in English, as in the document.

GET /me#

Check which shop, scopes and limits a key has.

Describes the key you are calling with: its scopes, shop, allow-lists and limits. Costs no quota; use it to check a key.

Required scope: any valid key

No parameters.

Responses
Status	Response schema	Description
`200`	`KeyInfo`	Successful Response
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.

Check a key (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/me' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/me", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/me",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "id": 3,
  "name": "Storefront search",
  "hint": "osk_…PLEE",
  "scopes": [
    "analytics:read",
    "answer",
    "catalogue:read",
    "similar",
    "suggest"
  ],
  "shop": {
    "domain": "alpha.example",
    "currency": "EUR",
    "language": "en"
  },
  "origins": [],
  "networks": [],
  "created_at": "2026-10-13T09:00:00+00:00",
  "last_used_at": null,
  "limits": {
    "answer": {
      "per_minute": 20
    },
    "suggest": {
      "per_minute": 120
    },
    "similar": {
      "per_minute": 60
    },
    "catalogue:read": {
      "per_minute": 120
    },
    "analytics:read": {
      "per_minute": 30
    }
  },
  "answers_per_day": 500
}

Missing or invalid key (HTTP 401)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/me'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/me", {
  method: "GET",
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/me",
)
print(response.status_code, response.json())

Example response · HTTP 401

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Missing or invalid API key. Send it as 'Authorization: Bearer osk_…'.",
    "param": null,
    "request_id": "req_9f2b000000000001"
  }
}

POST /answers#

Ask a question in the shopper's own words and get the best match, alternatives and a reason for each.

Answers a shopper's question the way the shop's own assistant does: the best match, alternatives and a one-line reason for each. Product facts (title, price, stock, link) always come from the shop's catalogue; only say and why are written by an AI model — see the ai object, and pass that on to your users.

Counted against the key's per-minute limit and its daily cap; a replay with the same Idempotency-Key is free.

Required scope: answer
Limit: 20 calls per 60 s

Parameters
Name	In	Type	Required	Constraints	Description
`Idempotency-Key`	`header`	`string \| null`	no	`length 1–64`	Makes a retry safe: the same key and body return the first answer without a second model call.

Request body: AnswerRequest#

Request schema
Field	Type	Required	Description
`query`	`string`	yes	The shopper's question, in their own words.
`language`	`Language \| null`	no	Language of the reply (`ru en el es de it fr`). Defaults to the shop's language.
`session_id`	`string \| null`	no	Opaque id of one conversation. Send the same id to let follow-ups (“cheaper”, “something lighter”) build on earlier turns. Sessions are private to your API key.
`in_stock_only`	`boolean`	no	Only products that can be bought now (excludes pre-orders).

Responses
Status	Response schema	Description
`200`	`Answer`	Successful Response
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`409`	`ErrorBody`	Same `Idempotency-Key` is still being processed.
`422`	`ErrorBody`	Invalid request body, or `Idempotency-Key` reused with a different body.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.
`502`	`ErrorBody`	The answer could not be produced right now. Safe to retry.

A shopper asks in their own words (HTTP 200)#

Example request, curl

curl -X POST 'https://assistant.onesite.agency/api/v1/answers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 3f9d1c52-7b0e-4a53-9a6f-0c2f8e1d77aa' \
  -d '{
  "query": "a cold, quiet science fiction novel for a long winter",
  "language": "en",
  "in_stock_only": true,
  "session_id": "visitor-8841"
}'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/answers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "3f9d1c52-7b0e-4a53-9a6f-0c2f8e1d77aa",
  },
  body: JSON.stringify({
    "query": "a cold, quiet science fiction novel for a long winter",
    "language": "en",
    "in_stock_only": true,
    "session_id": "visitor-8841"
  }),
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.post(
    "https://assistant.onesite.agency/api/v1/answers",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "3f9d1c52-7b0e-4a53-9a6f-0c2f8e1d77aa",
    },
    json={
        "query": "a cold, quiet science fiction novel for a long winter",
        "language": "en",
        "in_stock_only": True,
        "session_id": "visitor-8841",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "id": "6f1b4a52-3c0d-4d5e-9a7e-2b8c1d0f4e11",
  "query": "a cold, quiet science fiction novel for a long winter",
  "intent": "search",
  "say": "Here is the best match for a cold, quiet read.",
  "main": {
    "product": {
      "id": 101,
      "title": "The Left Hand of Darkness",
      "maker": "Ursula K. Le Guin",
      "line": "Hainish Cycle",
      "url": "https://alpha.example/products/101",
      "handle": "the-left-hand-of-darkness",
      "external_id": "gid://shop/101",
      "price": {
        "amount": "12.90",
        "currency": "EUR"
      },
      "availability": "in_stock",
      "ready_at": null,
      "image_url": "https://cdn.alpha.example/101.jpg",
      "thumb_url": "https://cdn.alpha.example/101-s.jpg"
    },
    "why": "A quiet, snowbound classic - the cold-world mood you described, in one of the genre's best-loved novels.",
    "why_source": "model"
  },
  "alternatives": [
    {
      "product": {
        "id": 102,
        "title": "The Dispossessed",
        "maker": "Ursula K. Le Guin",
        "line": "Hainish Cycle",
        "url": "https://alpha.example/products/102",
        "handle": "the-dispossessed",
        "external_id": "gid://shop/102",
        "price": {
          "amount": "13.50",
          "currency": "EUR"
        },
        "availability": "in_stock",
        "ready_at": null,
        "image_url": "https://cdn.alpha.example/102.jpg",
        "thumb_url": "https://cdn.alpha.example/102-s.jpg"
      },
      "why": "Set in the same universe: the politics of a desert moon instead of snow.",
      "why_source": "model"
    },
    {
      "product": {
        "id": 104,
        "title": "Solaris",
        "maker": "Stanislaw Lem",
        "line": null,
        "url": "https://alpha.example/products/104",
        "handle": "solaris",
        "external_id": "gid://shop/104",
        "price": {
          "amount": "11.00",
          "currency": "EUR"
        },
        "availability": "in_stock",
        "ready_at": null,
        "image_url": "https://cdn.alpha.example/104.jpg",
        "thumb_url": "https://cdn.alpha.example/104-s.jpg"
      },
      "why": "A different kind of stillness: an ocean planet that studies the people studying it.",
      "why_source": "model"
    }
  ],
  "shelves": [],
  "miss": false,
  "miss_reason": null,
  "clarify": null,
  "degraded": false,
  "currency": "EUR",
  "ai": {
    "generated": true,
    "fields": [
      "say",
      "main.why",
      "alternatives[].why"
    ],
    "notice": "The `say` and `why` texts are generated by an AI model from this shop's catalogue and may contain mistakes. Product names, prices, stock and links come from the shop's catalogue, not from the model."
  }
}

Rate limit reached (HTTP 429)#

Example request, curl

curl -X POST 'https://assistant.onesite.agency/api/v1/answers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "a cold, quiet science fiction novel for a long winter"
}'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/answers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "a cold, quiet science fiction novel for a long winter"
  }),
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.post(
    "https://assistant.onesite.agency/api/v1/answers",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "query": "a cold, quiet science fiction novel for a long winter",
    },
)
print(response.status_code, response.json())

Example response · HTTP 429

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Rate limit reached: 20 calls per minute for this scope.",
    "param": null,
    "request_id": "req_9f2b000000000005"
  }
}

GET /suggestions#

Fast product suggestions under a search box as someone types. No AI model is involved.

Instant products for a half-typed query. No model is called and nothing is journalled, so it is cheap — but it is not a substitute for POST /answers when the shopper asked a full question.

Required scope: suggest
Limit: 120 calls per 60 s

Parameters
Name	In	Type	Required	Constraints	Description
`q`	`query`	`string`	yes	`length 1–500`	What has been typed so far.
`limit`	`query`	`integer`	no	`1–20; default 6`
`in_stock_only`	`query`	`boolean`	no	`default false`	Only products that can be bought now.

Responses
Status	Response schema	Description
`200`	`SuggestionList`	Successful Response
`304`	–	Not modified: your `If-None-Match` matched the current `ETag`.
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`422`	`ErrorBody`	Invalid request.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.

Suggestions while the shopper types (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/suggestions?q=left+hand&limit=3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/suggestions?q=left+hand&limit=3", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/suggestions?q=left+hand&limit=3",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "object": "list",
  "query": "left hand",
  "data": [
    {
      "id": 101,
      "title": "The Left Hand of Darkness",
      "maker": "Ursula K. Le Guin",
      "line": "Hainish Cycle",
      "url": "https://alpha.example/products/101",
      "handle": "the-left-hand-of-darkness",
      "external_id": "gid://shop/101",
      "price": {
        "amount": "12.90",
        "currency": "EUR"
      },
      "availability": "in_stock",
      "ready_at": null,
      "image_url": "https://cdn.alpha.example/101.jpg",
      "thumb_url": "https://cdn.alpha.example/101-s.jpg"
    }
  ]
}

GET /products#

Read the whole catalogue page by page.

The shop's visible catalogue in a stable order (by product id), a page at a time. Products the owner has hidden or excluded are not listed. A page may hold fewer than limit items while has_more is still true; keep following next_cursor until it is null.

Required scope: catalogue:read
Limit: 120 calls per 60 s

Parameters
Name	In	Type	Required	Constraints	Description
`limit`	`query`	`integer`	no	`1–100; default 20`
`cursor`	`query`	`string \| null`	no	`length ≤ 64`	`next_cursor` of the previous page.

Responses
Status	Response schema	Description
`200`	`ProductPage`	Successful Response
`304`	–	Not modified: your `If-None-Match` matched the current `ETag`.
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`422`	`ErrorBody`	Invalid request.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.

First page of the catalogue (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/products?limit=2' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/products?limit=2", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/products?limit=2",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "object": "list",
  "data": [
    {
      "id": 101,
      "title": "The Left Hand of Darkness",
      "maker": "Ursula K. Le Guin",
      "line": "Hainish Cycle",
      "url": "https://alpha.example/products/101",
      "handle": "the-left-hand-of-darkness",
      "external_id": "gid://shop/101",
      "price": {
        "amount": "12.90",
        "currency": "EUR"
      },
      "availability": "in_stock",
      "ready_at": null,
      "image_url": "https://cdn.alpha.example/101.jpg",
      "thumb_url": "https://cdn.alpha.example/101-s.jpg"
    },
    {
      "id": 102,
      "title": "The Dispossessed",
      "maker": "Ursula K. Le Guin",
      "line": "Hainish Cycle",
      "url": "https://alpha.example/products/102",
      "handle": "the-dispossessed",
      "external_id": "gid://shop/102",
      "price": {
        "amount": "13.50",
        "currency": "EUR"
      },
      "availability": "in_stock",
      "ready_at": null,
      "image_url": "https://cdn.alpha.example/102.jpg",
      "thumb_url": "https://cdn.alpha.example/102-s.jpg"
    }
  ],
  "has_more": true,
  "next_cursor": "c1.MTAy"
}

Following the cursor (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/products?limit=2&cursor=c1.MTAy' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/products?limit=2&cursor=c1.MTAy", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/products?limit=2&cursor=c1.MTAy",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "object": "list",
  "data": [
    {
      "id": 103,
      "title": "A Wizard of Earthsea",
      "maker": "Ursula K. Le Guin",
      "line": "Earthsea",
      "url": "https://alpha.example/products/103",
      "handle": "a-wizard-of-earthsea",
      "external_id": "gid://shop/103",
      "price": {
        "amount": "9.99",
        "currency": "EUR"
      },
      "availability": "in_stock",
      "ready_at": null,
      "image_url": "https://cdn.alpha.example/103.jpg",
      "thumb_url": "https://cdn.alpha.example/103-s.jpg"
    },
    {
      "id": 104,
      "title": "Solaris",
      "maker": "Stanislaw Lem",
      "line": null,
      "url": "https://alpha.example/products/104",
      "handle": "solaris",
      "external_id": "gid://shop/104",
      "price": {
        "amount": "11.00",
        "currency": "EUR"
      },
      "availability": "in_stock",
      "ready_at": null,
      "image_url": "https://cdn.alpha.example/104.jpg",
      "thumb_url": "https://cdn.alpha.example/104-s.jpg"
    }
  ],
  "has_more": true,
  "next_cursor": "c1.MTA0"
}

A parameter out of range (HTTP 422)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/products?limit=500' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/products?limit=500", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/products?limit=500",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 422

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Invalid request. limit: Input should be less than or equal to 100",
    "param": "limit",
    "request_id": "req_9f2b000000000004"
  }
}

GET /products/{product_id}#

Read one product by its id.

One product of the shop with its description and gallery. A product that belongs to another shop, does not exist or is hidden by the owner is the same 404.

Required scope: catalogue:read
Limit: 120 calls per 60 s

Parameters
Name	In	Type	Required	Constraints	Description
`product_id`	`path`	`integer`	yes	`1–9223372036854776000`	Product number (`id` in any product object).

Responses
Status	Response schema	Description
`200`	`ProductDetail`	Successful Response
`304`	–	Not modified: your `If-None-Match` matched the current `ETag`.
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`404`	`ErrorBody`	No such visible product in this shop.
`422`	`ErrorBody`	Invalid request.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.

One product with its description and gallery (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/products/101' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/products/101", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/products/101",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "id": 101,
  "title": "The Left Hand of Darkness",
  "maker": "Ursula K. Le Guin",
  "line": "Hainish Cycle",
  "url": "https://alpha.example/products/101",
  "handle": "the-left-hand-of-darkness",
  "external_id": "gid://shop/101",
  "price": {
    "amount": "12.90",
    "currency": "EUR"
  },
  "availability": "in_stock",
  "ready_at": null,
  "image_url": "https://cdn.alpha.example/101.jpg",
  "thumb_url": "https://cdn.alpha.example/101-s.jpg",
  "description": "The Left Hand of Darkness by Ursula K. Le Guin.",
  "images": [
    "https://cdn.alpha.example/101.jpg"
  ]
}

A key without the needed scope (HTTP 403)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/products/101' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/products/101", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/products/101",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 403

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This key lacks the 'catalogue:read' scope. Create a key that has it.",
    "param": "catalogue:read",
    "request_id": "req_9f2b000000000002"
  }
}

A product that is not in this shop (HTTP 404)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/products/987654' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/products/987654", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/products/987654",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 404

{
  "error": {
    "type": "not_found_error",
    "code": "product_not_found",
    "message": "No such product in this shop.",
    "param": null,
    "request_id": "req_9f2b000000000003"
  }
}

GET /products/{product_id}/similar#

Products similar to one product. No AI model is involved.

Neighbours of the product's own embedding vector, ranked the way the shop's assistant ranks them. No model is called. Needs only the similar scope — a key without catalogue:read cannot fetch the product itself.

Required scope: similar
Limit: 60 calls per 60 s

Parameters
Name	In	Type	Required	Constraints	Description
`product_id`	`path`	`integer`	yes	`1–9223372036854776000`	Product number (`id` in any product object).
`limit`	`query`	`integer`	no	`1–24; default 8`

Responses
Status	Response schema	Description
`200`	`SimilarList`	Successful Response
`304`	–	Not modified: your `If-None-Match` matched the current `ETag`.
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`404`	`ErrorBody`	No such visible product in this shop.
`422`	`ErrorBody`	Invalid request.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.

Products similar to one product (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/products/101/similar?limit=3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/products/101/similar?limit=3", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/products/101/similar?limit=3",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "object": "list",
  "data": [
    {
      "id": 102,
      "title": "The Dispossessed",
      "maker": "Ursula K. Le Guin",
      "line": "Hainish Cycle",
      "url": "https://alpha.example/products/102",
      "handle": "the-dispossessed",
      "external_id": "gid://shop/102",
      "price": {
        "amount": "13.50",
        "currency": "EUR"
      },
      "availability": "in_stock",
      "ready_at": null,
      "image_url": "https://cdn.alpha.example/102.jpg",
      "thumb_url": "https://cdn.alpha.example/102-s.jpg"
    },
    {
      "id": 103,
      "title": "A Wizard of Earthsea",
      "maker": "Ursula K. Le Guin",
      "line": "Earthsea",
      "url": "https://alpha.example/products/103",
      "handle": "a-wizard-of-earthsea",
      "external_id": "gid://shop/103",
      "price": {
        "amount": "9.99",
        "currency": "EUR"
      },
      "availability": "in_stock",
      "ready_at": null,
      "image_url": "https://cdn.alpha.example/103.jpg",
      "thumb_url": "https://cdn.alpha.example/103-s.jpg"
    },
    {
      "id": 109,
      "title": "Gift Cookbook",
      "maker": "Chef Example",
      "line": null,
      "url": "https://alpha.example/products/109",
      "handle": "gift-cookbook",
      "external_id": "gid://shop/109",
      "price": {
        "amount": "24.00",
        "currency": "EUR"
      },
      "availability": "in_stock",
      "ready_at": null,
      "image_url": "https://cdn.alpha.example/109.jpg",
      "thumb_url": "https://cdn.alpha.example/109-s.jpg"
    }
  ],
  "product_id": 101
}

GET /analytics/summary#

Your shop's totals for a window — the same figures as the cabinet's Statistics — with an optional comparison.

The cabinet's Statistics figures for the window: questions, people who asked, sessions, found and not found, clicks, and the shopper's path by step. Counted for people only. With compare, the same totals for the comparison window — only when the shop's history covers it; otherwise previous is null rather than a growth from nothing.

Required scope: analytics:read
Limit: 30 calls per 60 s

Parameters
Name	In	Type	Required	Constraints	Description
`compare`	`query`	`"prev" \| "year" \| "none"`	no	`default "prev"`	Compare with the window just before (`prev`), the same window a year back (`year`), or nothing.
`since`	`query`	`string (date-time) \| null`	no		Start of the window (ISO 8601; without an offset — UTC). Default: `until` minus 30 days.
`until`	`query`	`string (date-time) \| null`	no		End of the window, exclusive (ISO 8601). Default: now.
`first_day`	`query`	`string (date) \| null`	no		First day of the window (`YYYY-MM-DD`) in `timezone`, inclusive. Use with `last_day` instead of `since`/`until`.
`last_day`	`query`	`string (date) \| null`	no		Last day of the window (`YYYY-MM-DD`) in `timezone`, inclusive.
`timezone`	`query`	`string \| null`	no	`length ≤ 64`	IANA time zone for days, e.g. `Europe/Berlin`. Default: the shop's time zone, or UTC when the shop has none.

Responses
Status	Response schema	Description
`200`	`AnalyticsSummary`	Successful Response
`304`	–	Not modified: your `If-None-Match` matched the current `ETag`.
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`422`	`ErrorBody`	Invalid request.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.

Last week in figures, compared with the week before (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/analytics/summary?first_day=2026-10-06&last_day=2026-10-12' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/analytics/summary?first_day=2026-10-06&last_day=2026-10-12", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/analytics/summary?first_day=2026-10-06&last_day=2026-10-12",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "object": "analytics.summary",
  "window": {
    "since": "2026-10-06T00:00:00+00:00",
    "until": "2026-10-13T00:00:00+00:00",
    "timezone": "UTC"
  },
  "totals": {
    "queries": 280,
    "people": 154,
    "sessions": 174,
    "answered": 238,
    "missed": 42,
    "asked_again": 31,
    "impressions": 840,
    "clicks": 82,
    "reached": 63,
    "browsed": 7
  },
  "compare": "prev",
  "previous_window": {
    "since": "2026-09-29T00:00:00+00:00",
    "until": "2026-10-06T00:00:00+00:00"
  },
  "previous": {
    "queries": 273,
    "people": 150,
    "sessions": 174,
    "answered": 238,
    "missed": 42,
    "asked_again": 31,
    "impressions": 840,
    "clicks": 82,
    "reached": 63,
    "browsed": 7
  },
  "funnel": [
    {
      "stage": "visit",
      "sessions": 900,
      "share_of_previous": null
    },
    {
      "stage": "offered",
      "sessions": 860,
      "share_of_previous": 0.9555555555555556
    },
    {
      "stage": "opened",
      "sessions": 140,
      "share_of_previous": 0.16279069767441862
    },
    {
      "stage": "asked",
      "sessions": 120,
      "share_of_previous": 0.8571428571428571
    },
    {
      "stage": "reached",
      "sessions": 30,
      "share_of_previous": 0.25
    },
    {
      "stage": "carted",
      "sessions": 70,
      "share_of_previous": null
    },
    {
      "stage": "bought",
      "sessions": 12,
      "share_of_previous": 0.17142857142857143
    }
  ],
  "funnel_since": null
}

GET /analytics/series#

Questions, misses and questions that reached a product, for every day of the window.

Questions, misses and questions that reached a product, for every day of the window in timezone. Days without questions are zeros. Only the window is counted, so the first and last day may be partial, and the days add up to the summary's totals.

Required scope: analytics:read
Limit: 30 calls per 60 s

Parameters
Name	In	Type	Required	Constraints	Description
`since`	`query`	`string (date-time) \| null`	no		Start of the window (ISO 8601; without an offset — UTC). Default: `until` minus 30 days.
`until`	`query`	`string (date-time) \| null`	no		End of the window, exclusive (ISO 8601). Default: now.
`first_day`	`query`	`string (date) \| null`	no		First day of the window (`YYYY-MM-DD`) in `timezone`, inclusive. Use with `last_day` instead of `since`/`until`.
`last_day`	`query`	`string (date) \| null`	no		Last day of the window (`YYYY-MM-DD`) in `timezone`, inclusive.
`timezone`	`query`	`string \| null`	no	`length ≤ 64`	IANA time zone for days, e.g. `Europe/Berlin`. Default: the shop's time zone, or UTC when the shop has none.

Responses
Status	Response schema	Description
`200`	`AnalyticsSeries`	Successful Response
`304`	–	Not modified: your `If-None-Match` matched the current `ETag`.
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`422`	`ErrorBody`	Invalid request.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.

Questions per day (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/analytics/series?first_day=2026-10-06&last_day=2026-10-12&timezone=Europe/Berlin' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/analytics/series?first_day=2026-10-06&last_day=2026-10-12&timezone=Europe/Berlin", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/analytics/series?first_day=2026-10-06&last_day=2026-10-12&timezone=Europe/Berlin",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "object": "analytics.series",
  "window": {
    "since": "2026-10-05T22:00:00+00:00",
    "until": "2026-10-12T22:00:00+00:00",
    "timezone": "Europe/Berlin"
  },
  "data": [
    {
      "date": "2026-10-06",
      "queries": 40,
      "missed": 6,
      "reached": 9
    },
    {
      "date": "2026-10-07",
      "queries": 40,
      "missed": 6,
      "reached": 9
    },
    {
      "date": "2026-10-08",
      "queries": 40,
      "missed": 6,
      "reached": 9
    },
    {
      "date": "2026-10-09",
      "queries": 40,
      "missed": 6,
      "reached": 9
    },
    {
      "date": "2026-10-10",
      "queries": 40,
      "missed": 6,
      "reached": 9
    },
    {
      "date": "2026-10-11",
      "queries": 40,
      "missed": 6,
      "reached": 9
    },
    {
      "date": "2026-10-12",
      "queries": 40,
      "missed": 6,
      "reached": 9
    }
  ]
}

GET /analytics/queries#

The questions people ask most, and the questions most often left without a product.

The questions people ask most, and the questions most often left without a product — what to stock and what to describe better. Questions are grouped without regard to case; e-mail addresses and phone or card numbers in them are masked.

Required scope: analytics:read
Limit: 30 calls per 60 s

Parameters
Name	In	Type	Required	Constraints	Description
`limit`	`query`	`integer`	no	`1–100; default 20`	Rows in each list.
`since`	`query`	`string (date-time) \| null`	no		Start of the window (ISO 8601; without an offset — UTC). Default: `until` minus 30 days.
`until`	`query`	`string (date-time) \| null`	no		End of the window, exclusive (ISO 8601). Default: now.
`first_day`	`query`	`string (date) \| null`	no		First day of the window (`YYYY-MM-DD`) in `timezone`, inclusive. Use with `last_day` instead of `since`/`until`.
`last_day`	`query`	`string (date) \| null`	no		Last day of the window (`YYYY-MM-DD`) in `timezone`, inclusive.
`timezone`	`query`	`string \| null`	no	`length ≤ 64`	IANA time zone for days, e.g. `Europe/Berlin`. Default: the shop's time zone, or UTC when the shop has none.

Responses
Status	Response schema	Description
`200`	`AnalyticsQueries`	Successful Response
`304`	–	Not modified: your `If-None-Match` matched the current `ETag`.
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`422`	`ErrorBody`	Invalid request.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.

What people ask most, and what they do not find (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/analytics/queries?first_day=2026-10-06&last_day=2026-10-12&limit=3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/analytics/queries?first_day=2026-10-06&last_day=2026-10-12&limit=3", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/analytics/queries?first_day=2026-10-06&last_day=2026-10-12&limit=3",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "object": "analytics.queries",
  "window": {
    "since": "2026-10-06T00:00:00+00:00",
    "until": "2026-10-13T00:00:00+00:00",
    "timezone": "UTC"
  },
  "top": [
    {
      "text": "science fiction for winter",
      "count": 42,
      "missed": 0,
      "clicks": 28
    },
    {
      "text": "gift for a ten-year-old",
      "count": 28,
      "missed": 7,
      "clicks": 14
    },
    {
      "text": "write to me at [email]",
      "count": 1,
      "missed": 1,
      "clicks": 0
    }
  ],
  "missed": [
    {
      "text": "signed first editions",
      "count": 21,
      "missed": 21,
      "clicks": 0
    },
    {
      "text": "gift for a ten-year-old",
      "count": 28,
      "missed": 7,
      "clicks": 14
    }
  ]
}

GET /analytics/sales#

What the assistant sold, by your own orders — the same figures as the cabinet's Purchases summary.

Orders and revenue the assistant helped with, by the shop's own orders: products its button put into the cart and products bought after it showed them. Orders after a conversation without either are counted apart and not as its revenue. The shop's total turnover is not part of this API.

Required scope: analytics:read
Limit: 30 calls per 60 s

Parameters
Name	In	Type	Required	Constraints	Description
`days`	`query`	`integer`	no	`default 30`	Period: today and the days before it. One of 7, 30, 90.
`timezone`	`query`	`string \| null`	no	`length ≤ 64`	IANA time zone for days. Default: the shop's time zone, or UTC.

Responses
Status	Response schema	Description
`200`	`AnalyticsSales`	Successful Response
`304`	–	Not modified: your `If-None-Match` matched the current `ETag`.
`401`	`ErrorBody`	Missing, malformed, unknown or revoked API key (all look the same).
`402`	`ErrorBody`	The shop's subscription is not active.
`403`	`ErrorBody`	Key not allowed here: missing scope, IP or origin not on the key's list, plan without API.
`422`	`ErrorBody`	Invalid request.
`429`	`ErrorBody`	Rate limit or daily quota reached. See `Retry-After`.

What the assistant sold in the last 7 days (HTTP 200)#

Example request, curl

curl 'https://assistant.onesite.agency/api/v1/analytics/sales?days=7' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example request, JavaScript (fetch)

const response = await fetch("https://assistant.onesite.agency/api/v1/analytics/sales?days=7", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
const data = await response.json();
console.log(response.status, data);

Example request, Python (requests)

import requests

response = requests.get(
    "https://assistant.onesite.agency/api/v1/analytics/sales?days=7",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.json())

Example response · HTTP 200

{
  "object": "analytics.sales",
  "days": 7,
  "since": "2026-10-07T00:00:00+00:00",
  "timezone": "UTC",
  "currency": "EUR",
  "assistant_orders": 2,
  "assistant_revenue": {
    "amount": "23.90",
    "currency": "EUR"
  },
  "button_revenue": {
    "amount": "12.90",
    "currency": "EUR"
  },
  "shown_revenue": {
    "amount": "11.00",
    "currency": "EUR"
  },
  "carted": 3,
  "talked_orders": 1,
  "average_order": {
    "amount": "18.70",
    "currency": "EUR"
  },
  "days_data": [
    {
      "date": "2026-10-07",
      "orders": 0,
      "revenue": {
        "amount": "0.00",
        "currency": "EUR"
      }
    },
    {
      "date": "2026-10-08",
      "orders": 0,
      "revenue": {
        "amount": "0.00",
        "currency": "EUR"
      }
    },
    {
      "date": "2026-10-09",
      "orders": 0,
      "revenue": {
        "amount": "0.00",
        "currency": "EUR"
      }
    },
    {
      "date": "2026-10-10",
      "orders": 0,
      "revenue": {
        "amount": "0.00",
        "currency": "EUR"
      }
    },
    {
      "date": "2026-10-11",
      "orders": 1,
      "revenue": {
        "amount": "11.00",
        "currency": "EUR"
      }
    },
    {
      "date": "2026-10-12",
      "orders": 0,
      "revenue": {
        "amount": "0.00",
        "currency": "EUR"
      }
    },
    {
      "date": "2026-10-13",
      "orders": 1,
      "revenue": {
        "amount": "12.90",
        "currency": "EUR"
      }
    }
  ],
  "products": [
    {
      "product_id": 101,
      "title": "The Left Hand of Darkness",
      "quantity": 1,
      "revenue": {
        "amount": "12.90",
        "currency": "EUR"
      }
    },
    {
      "product_id": 104,
      "title": "Solaris",
      "quantity": 1,
      "revenue": {
        "amount": "11.00",
        "currency": "EUR"
      }
    }
  ]
}

Data types#

The objects used in requests and responses. | null means the field is always present but may be null; an array is written Type[].

AiDisclosure#

Shown to your users? Then say so. The wording below is the minimum we ask integrations to pass on.

AiDisclosure
Field	Type	Required	Description
`generated`	`boolean`	no	Some text in this response was written by an AI model.
`fields`	`string[]`	yes	JSON paths of the AI-written strings.
`notice`	`string`	yes

AnalyticsFunnelStep#

AnalyticsFunnelStep
Field	Type	Required	Description
`stage`	`"visit" \| "offered" \| "opened" \| "asked" \| "reached" \| "carted" \| "bought"`	yes
`sessions`	`integer`	yes	Sessions that reached this step. Sessions, not people: events on the site carry no visitor mark.
`share_of_previous`	`number \| null`	no	`sessions` divided by the previous step. `null` on the first step and where a step is larger than the one before it (for example, carts added with the shop's own button without a click in an answer).

AnalyticsPeriod#

AnalyticsPeriod
Field	Type	Required	Description
`since`	`string`	yes
`until`	`string`	yes

AnalyticsPoint#

AnalyticsPoint
Field	Type	Required	Description
`date`	`string`	yes	The day (`YYYY-MM-DD`) in `window.timezone`. The first and last day may be partial: only the window is counted.
`queries`	`integer`	yes
`missed`	`integer`	yes
`reached`	`integer`	yes	Questions of the day after which the shopper opened a product page from the answer.

AnalyticsQueries#

AnalyticsQueries
Field	Type	Required	Description
`object`	`"analytics.queries"`	no
`window`	`AnalyticsWindow`	yes
`top`	`AnalyticsQuery[]`	yes	Most frequent questions, most frequent first.
`missed`	`AnalyticsQuery[]`	yes	Questions most often left without a product, by number of misses. Its own list, not a filter of `top`.

AnalyticsQuery#

AnalyticsQuery
Field	Type	Required	Description
`text`	`string`	yes	The question as asked (case-insensitive group). E-mail addresses, phone and card numbers are masked.
`count`	`integer`	yes	How many times it was asked.
`missed`	`integer`	yes	How many of those had nothing to show.
`clicks`	`integer`	yes	Clicks from its answers to product pages.

AnalyticsSales#

What the assistant sold, by the shop's own orders — the same figures as the summary in the cabinet's Purchases section.

AnalyticsSales
Field	Type	Required	Description
`object`	`"analytics.sales"`	no
`days`	`integer`	yes	Today and the days before it, from midnight in `timezone`.
`since`	`string`	yes	Midnight of the first day (ISO 8601).
`timezone`	`string`	yes
`currency`	`string`	yes	Orders in another currency are not added up.
`assistant_orders`	`integer`	yes	Orders with a product added to the cart by the assistant's button or bought after the assistant showed it.
`assistant_revenue`	`Money`	yes	The value of those products (not the whole orders).
`button_revenue`	`Money`	yes	Part of `assistant_revenue` added to the cart by the assistant's button.
`shown_revenue`	`Money`	yes	Part of `assistant_revenue` bought after the assistant showed the product.
`carted`	`integer`	yes	Products the assistant helped to put into a cart in the period (by its button or after showing them).
`talked_orders`	`integer`	yes	Orders placed after a conversation with the assistant without any of the above. Not counted as its revenue.
`average_order`	`Money \| null`	no	Average total of `assistant_orders`; `null` when none has a total.
`days_data`	`AnalyticsSalesDay[]`	yes	Every day of the period, empty days included.
`products`	`AnalyticsSoldProduct[]`	yes	Top products sold through the assistant, by revenue.

AnalyticsSalesDay#

AnalyticsSalesDay
Field	Type	Required	Description
`date`	`string`	yes	The day (`YYYY-MM-DD`) in `timezone`.
`orders`	`integer`	yes
`revenue`	`Money`	yes

AnalyticsSeries#

AnalyticsSeries
Field	Type	Required	Description
`object`	`"analytics.series"`	no
`window`	`AnalyticsWindow`	yes
`data`	`AnalyticsPoint[]`	yes	Every day of the window, days without questions included as zeros. The sum of `queries` equals `totals.queries` of the summary.

AnalyticsSoldProduct#

AnalyticsSoldProduct
Field	Type	Required	Description
`product_id`	`integer \| null`	no	`null` when the product is no longer in the catalogue.
`title`	`string \| null`	no
`quantity`	`integer`	yes
`revenue`	`Money`	yes

AnalyticsSummary#

AnalyticsSummary
Field	Type	Required	Description
`object`	`"analytics.summary"`	no
`window`	`AnalyticsWindow`	yes
`totals`	`AnalyticsTotals`	yes
`compare`	`"prev" \| "year" \| "none"`	yes
`previous_window`	`AnalyticsPeriod \| null`	no	The window compared with. `null` when `compare` is `none` or the shop's history covers less than 90 % of it.
`previous`	`AnalyticsTotals \| null`	no	Totals of `previous_window`, counted the same way. `null` — no comparison.
`funnel`	`AnalyticsFunnelStep[]`	yes	Sessions by step of the shopper's path, in order.
`funnel_since`	`string \| null`	no	Set when the funnel is counted from a later moment than `window.since`: before it one of the steps was not yet recorded.

AnalyticsTotals#

Counted for people only: bots, our own checks, calls made with API keys and conversations removed by the operator are not counted.

AnalyticsTotals
Field	Type	Required	Description
`queries`	`integer`	yes	Questions people asked the assistant, in their own words.
`people`	`integer`	yes	Different people who asked at least once, by the visitor mark in their browser: someone back three days later is one person, the same person on phone and laptop is two. A question without the mark (no analytics consent) counts its session.
`sessions`	`integer`	yes	Different sessions with at least one question. A session lasts about a day, so this is not people.
`answered`	`integer`	yes	Questions answered with at least one product.
`missed`	`integer`	yes	Questions with nothing to show.
`asked_again`	`integer`	yes	Sessions that asked another question after an answer.
`impressions`	`integer`	yes	Product cards shown in answers.
`clicks`	`integer`	yes	Clicks from answer cards to product pages.
`reached`	`integer`	yes	Questions after which the shopper opened a product page from the answer. Counted per question, not per click.
`browsed`	`integer`	yes	Clicks to product pages from shelves and collections, with no question before them.

AnalyticsWindow#

AnalyticsWindow
Field	Type	Required	Description
`since`	`string`	yes	Start of the window, inclusive (ISO 8601, UTC).
`until`	`string`	yes	End of the window, exclusive (ISO 8601, UTC).
`timezone`	`string`	yes	IANA time zone in which days are cut (daily series, `first_day`/`last_day`).

Answer#

Answer
Field	Type	Required	Description
`id`	`string`	yes	Id of this answer in the shop's journal. Quote it when you report a problem.
`query`	`string`	yes
`intent`	`string`	yes	What the question was understood to be: `search`, `browse`, `basket`, `question`, `greeting`, `off_topic`, `code`, `about_item`, `order`…. New values may appear; treat unknown ones as `search`.
`say`	`string \| null`	no	A short spoken-style reply, written by an AI model. May be `null`.
`main`	`Recommendation \| null`	no	The single best match, when there is one.
`alternatives`	`Recommendation[]`	no
`shelves`	`Shelf[]`	no	For “everything by …” questions: whole shelves instead of picks.
`miss`	`boolean`	yes	`true` when the shop has nothing that fits. Do not invent a product then.
`miss_reason`	`"absent" \| "unstocked" \| "unmatched" \| null`	no	Why nothing is shown: not in the catalogue (`absent`), sold out (`unstocked`), or nothing matched the question's hard limits such as price (`unmatched`).
`clarify`	`string \| null`	no	A clarifying question to ask the user, when the answer needs one.
`degraded`	`boolean`	no	`true` when the answer was built without the model (it was unavailable).
`currency`	`string`	yes
`ai`	`AiDisclosure`	yes

AnswerRequest#

AnswerRequest
Field	Type	Required	Description
`query`	`string`	yes	The shopper's question, in their own words.
`language`	`Language \| null`	no	Language of the reply (`ru en el es de it fr`). Defaults to the shop's language.
`session_id`	`string \| null`	no	Opaque id of one conversation. Send the same id to let follow-ups (“cheaper”, “something lighter”) build on earlier turns. Sessions are private to your API key.
`in_stock_only`	`boolean`	no	Only products that can be bought now (excludes pre-orders).

ErrorBody#

ErrorBody
Field	Type	Required	Description
`error`	`ErrorDetail`	yes

ErrorDetail#

ErrorDetail
Field	Type	Required	Description
`type`	`"authentication_error" \| "permission_error" \| "invalid_request_error" \| "not_found_error" \| "conflict_error" \| "rate_limit_error" \| "billing_error" \| "api_error"`	yes
`code`	`string`	yes	Stable machine-readable reason. Branch on this, not on `message`.
`message`	`string`	yes	For humans. The wording may change between releases.
`param`	`string \| null`	no	The offending field or parameter, for `invalid_request`.
`request_id`	`string`	yes	Also in the `X-Request-Id` response header.

KeyInfo#

KeyInfo
Field	Type	Required	Description
`id`	`integer`	yes
`name`	`string`	yes
`hint`	`string`	yes	Which key this is, e.g. `osk_…x9Zq`. The secret itself is never shown again.
`scopes`	`string[]`	yes
`shop`	`KeyShop`	yes
`origins`	`string[]`	yes	Browser origins allowed to use this key. Empty = any (server-side use).
`networks`	`string[]`	yes	IP networks the key is accepted from. Empty = any.
`created_at`	`string`	yes
`last_used_at`	`string \| null`	no
`limits`	`map<string, ScopeLimit>`	yes	Calls per minute, per scope.
`answers_per_day`	`integer`	yes	Daily cap on `POST /answers` calls for this key (UTC day).

KeyShop#

KeyShop
Field	Type	Required
`domain`	`string`	yes
`currency`	`string`	yes
`language`	`string`	yes

Language#

Language code: ru, en, el, es, de, it, fr.

"ru" | "en" | "el" | "es" | "de" | "it" | "fr"

Money#

Money
Field	Type	Required	Description
`amount`	`string`	yes	Decimal amount as a string, e.g. `"12.90"`. Never a float: no rounding surprises.
`currency`	`string`	yes	ISO 4217 code of the shop currency, e.g. `EUR`.

Product#

A catalogue card. Everything here comes from the shop's own catalogue, never from the model.

Product
Field	Type	Required	Description
`id`	`integer`	yes	Product number in this shop's catalogue. Stable until the product is removed from the shop.
`title`	`string`	yes
`maker`	`string \| null`	no	Whoever the shop credits as the maker of the product.
`line`	`string \| null`	no	Series, collection or product line, when the shop names one.
`url`	`string \| null`	no	Product page on the shop's own site.
`handle`	`string \| null`	no	The platform's product handle (Shopify handle, WooCommerce slug), when known.
`external_id`	`string \| null`	no	The shop platform's own product id, for mapping back to your system.
`price`	`Money \| null`	no	Current price; `null` when the shop does not publish one.
`availability`	`"in_stock" \| "preorder" \| "out_of_stock"`	yes
`ready_at`	`string \| null`	no	For `preorder`: the shop's promised ship date (ISO 8601).
`image_url`	`string \| null`	no
`thumb_url`	`string \| null`	no	A smaller image, when the shop has one.

ProductDetail#

ProductDetail
Field	Type	Required	Description
`id`	`integer`	yes	Product number in this shop's catalogue. Stable until the product is removed from the shop.
`title`	`string`	yes
`maker`	`string \| null`	no	Whoever the shop credits as the maker of the product.
`line`	`string \| null`	no	Series, collection or product line, when the shop names one.
`url`	`string \| null`	no	Product page on the shop's own site.
`handle`	`string \| null`	no	The platform's product handle (Shopify handle, WooCommerce slug), when known.
`external_id`	`string \| null`	no	The shop platform's own product id, for mapping back to your system.
`price`	`Money \| null`	no	Current price; `null` when the shop does not publish one.
`availability`	`"in_stock" \| "preorder" \| "out_of_stock"`	yes
`ready_at`	`string \| null`	no	For `preorder`: the shop's promised ship date (ISO 8601).
`image_url`	`string \| null`	no
`thumb_url`	`string \| null`	no	A smaller image, when the shop has one.
`description`	`string \| null`	no
`images`	`string[]`	no	The shop's gallery, in the shop's order.

ProductPage#

ProductPage
Field	Type	Required	Description
`object`	`"list"`	no
`data`	`Product[]`	yes
`has_more`	`boolean`	yes
`next_cursor`	`string \| null`	no	Pass as `cursor` to get the next page. `null` on the last page.

Recommendation#

Recommendation
Field	Type	Required	Description
`product`	`Product`	yes
`why`	`string \| null`	no	One sentence on why this fits the question. Written by an AI model when `why_source` is `model`; a fixed catalogue template when it is `catalogue`.
`why_source`	`"model" \| "catalogue" \| null`	no	Who wrote `why`. `null` when there is no `why`.

ScopeLimit#

ScopeLimit
Field	Type	Required	Description
`per_minute`	`integer`	yes

Shelf#

Shelf
Field	Type	Required	Description
`title`	`string`	yes
`total`	`integer`	yes	How many products the shelf holds in the shop — not how many are shown in `items`.
`items`	`Product[]`	yes

SimilarList#

SimilarList
Field	Type	Required
`object`	`"list"`	no
`data`	`Product[]`	yes
`product_id`	`integer`	yes

SuggestionList#

SuggestionList
Field	Type	Required
`object`	`"list"`	no
`query`	`string`	yes
`data`	`Product[]`	yes

Errors#

Every error has the same shape and a request_id (also in the X-Request-Id header): quote it when you write to us. Branch on code, never on message, whose wording can change.

Errors · HTTP 422

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Invalid request. limit: Input should be less than or equal to 100",
    "param": "limit",
    "request_id": "req_9f2b000000000004"
  }
}

Error codes
Code	HTTP	What it means and what to do	Retry
`invalid_api_key`	`401`	The key is missing, malformed, unknown or revoked. All four look the same on purpose. Send `Authorization: Bearer <key>` or create a new key.	fix the request
`ip_not_allowed`	`403`	The key has an IP allow-list and this address is not on it. Call from a listed network or change the list in the cabinet.	fix the request
`origin_not_allowed`	`403`	The call comes from a browser page whose origin is not on the key's origin list. Add the exact origin (scheme, host, port) in the cabinet.	fix the request
`insufficient_scope`	`403`	The key does not have the scope this endpoint needs. Scopes cannot be widened: create a new key with the scope.	fix the request
`api_disabled`	`403`	The developer API is not switched on for this shop. Open the Developers tab in the cabinet, or contact us if you do not see it.	fix the request
`subscription_inactive`	`402`	The shop's subscription is not active, so the API is paused. It resumes by itself when the subscription is active again; the keys stay valid.	fix the request
`plan_not_entitled`	`403`	The shop's plan does not include the developer API. It is available on plans that include it.	fix the request
`rate_limited`	`429`	The per-minute limit for this key and scope is used up. Wait for `Retry-After` seconds and retry; spread calls out or cache results.	later
`daily_quota_exceeded`	`429`	The daily cap on answers for this key is reached (UTC day). Retry after `Retry-After` seconds, i.e. after the day rolls over.	later
`too_many_failed_attempts`	`429`	Too many invalid keys came from this address. Wait for `Retry-After` seconds, and check which key your code sends.	later
`invalid_request`	`422`	A parameter or body field is missing or out of range. `param` names the first offender; fix the request, retrying will not help.	fix the request
`invalid_cursor`	`422`	The cursor was altered or does not belong to this list. Pass `next_cursor` exactly as received, or start again without a cursor.	fix the request
`product_not_found`	`404`	There is no such product in this shop. Another shop's product id answers the same: a key reads only its own shop.	fix the request
`idempotency_key_reused`	`422`	This `Idempotency-Key` was already used with a different body. Use a new key for a different question.	fix the request
`idempotency_in_progress`	`409`	A request with the same `Idempotency-Key` is still being processed. Wait a moment and send the same request again to get its result.	later
`request_too_large`	`413`	The request body is larger than the limit. Send a smaller body.	fix the request
`answer_unavailable`	`502`	The answer could not be produced right now. Retry shortly with the same `Idempotency-Key`.	later
`internal_error`	`500`	Something went wrong on our side. Retry with a pause; if it persists, send us the `request_id`.	later
`not_found`	`404`	No such endpoint. Check the path against the reference; paths start with the version, `/api/v1`.	fix the request
`method_not_allowed`	`405`	The path exists but not for this HTTP method. The `Allow` header lists the allowed ones.	fix the request

type groups codes: authentication_error, permission_error, invalid_request_error, not_found_error, conflict_error, rate_limit_error, billing_error, api_error. New codes can appear within v1; treat an unknown code by its HTTP status.

Pagination#

Lists use cursors. Pass next_cursor from a response as cursor in the next request until next_cursor is null. limit defaults to 20 and is at most 100. A page may hold fewer items than limit while has_more is true, so follow next_cursor rather than counting. Treat a cursor as opaque: an altered one gives 422 invalid_cursor.

Caching and ETag#

GET responses carry an ETag. Send it back as If-None-Match; if nothing changed you get 304 Not Modified with no body, which is faster and lighter than downloading the list again. Cache catalogue reads on your side and revalidate this way.

Idempotency and retries#

POST /answers accepts an Idempotency-Key header (1 to 64 characters: letters, digits and . _ : -). Repeating the same body within 24 hours returns the first answer without a second model call and without using quota; the replay carries Idempotent-Replayed: true. The same key with a different body is 422 idempotency_key_reused; while the first request still runs you get 409 idempotency_in_progress.

Create a fresh UUID for each user question and reuse it only for retries of that very question.

Request bodies are limited to 16384 bytes (413 request_too_large).

Browsers and CORS#

A web page can call the API only from an origin listed on the key (scheme, host and port, for example https://shop.example); the API sends CORS headers only to listed origins. Anything in a page's code is public, so a key used there can be copied by anyone who opens the page.

So for browser use give the key only the suggest and similar scopes and an origin list, and keep answer keys on your server.

Analytics#

The analytics:read scope opens your shop's own figures: the same totals, daily series, top questions and assistant sales as the cabinet, computed by the same code. Give it only to keys that stay on your server.

Only people are counted: bots, our own checks, calls made with API keys and conversations removed by the operator are not. people counts different visitors by the mark in their browser — someone back three days later is one person, the same person on phone and laptop is two; sessions last about a day; funnel steps are sessions. The shop's total turnover is not part of the API.

A window is either since/until (ISO 8601; without an offset — UTC) or first_day/last_day, both days included, cut in timezone (default: the shop's time zone, or UTC). A comparison (compare) is returned only when the shop's history covers the comparison window; otherwise previous is null.

AI-generated text#

In an answer, say and every why are written by an AI model, and the response says so in its ai object: generated, the JSON paths in fields, and a notice text. If you show these texts to your users, tell your users that they are AI-generated; notice is the minimum wording we ask integrations to pass on.

Product names, prices, stock and links never come from the model. When miss is true the shop has nothing that fits: show that, and do not invent a product.

Versioning#

The version is part of the path: /v1. Within v1 we make only backward-compatible changes: new endpoints, new optional parameters, new response fields and new values of enumerations (for example new intent values). Write clients that ignore unknown fields and fall back sensibly on unknown enum values. A breaking change would only ever ship under a new version path.

For machines and AI assistants#

The same reference in machine-readable form. Import the OpenAPI document into Postman, Insomnia or a code generator.