Authentication

Ragnetiq issues your key. Each product has its own keys and a key only works with its product's API; the prefix tells them apart:

Product	Key prefix	API base URL
AI asistent	`as_`	`https://asistent.ragnetiq.com/api/stats/v1`
Smart Search	`ss_`	`https://search.ragnetiq.com/api/stats/v1`
SmartBox	`sb_`	`https://smartbox.ragnetiq.com/api/stats/v1`

A key is the prefix followed by 64 hexadecimal characters. Send it in the Authorization header with every request:

Authorization: Bearer sb_9f2c1a7e…

The key is as secret as a password. Use it from a server only (cron, backend, ETL), never in a browser or a mobile app. If it leaks, tell us: we revoke the old key and issue a new one; a revoked key stops working at once.

A missing, invalid or revoked key gets 401 unauthorized. A key without access to the requested data (a store, and with SmartBox and the AI assistant also a language version) gets 403 forbidden.

Requests and responses

Requests are GET only; the API changes nothing.
Responses are JSON in UTF-8 with cache-control: no-store.
Record times (occurred_at) are ISO 8601 in UTC.
Revenue in different currencies is never added up; it is split by currency.
We keep no personal data of your customers: visitor and session identifiers are random.

Period

You choose the period with query parameters:

Parameter	Value	Meaning
`from`	`YYYY-MM-DD`, optional	First day of the period (inclusive). Defaults to 29 days before `to`.
`to`	`YYYY-MM-DD`, optional	Last day of the period (inclusive). Defaults to today. At most 366 days.
`after`, `limit`	integers	Paging of the raw data, see below.

A day runs from midnight to midnight in Bratislava (Europe/Bratislava), as in the dashboard; every response states it in the timezone field.

Paging

The raw-data endpoints (Smart Search /events and /purchases, SmartBox /events and /orders) return at most 1,000 records at a time, oldest first. The response contains next: the id of the page's last record, or null when there is no further page. Ask for the next page with after=<next>. limit sets the page size (1 – 1,000, default 1,000).

Record ids are stable and grow over time, so after also works for incremental downloads: remember the last id and start from it next time.

One exception: the AI assistant's conversations (/conversations) have at most 200 records per page and next is an opaque cursor, not a number; send it back in after the same way. See AI assistant.

Limits

At most 120 requests per minute per key; above that you get 429 rate_limited.
At most 366 days per request; download longer history in parts.
Data is available within seconds, so today's numbers keep changing. For closed numbers, download yesterday and earlier.

Errors

An error response always has the same shape: an HTTP status code, error with a machine-readable code and message with an explanation.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{ "error": "forbidden", "message": "Kľúč nemá prístup k niektorému z požadovaných obchodov." }

HTTP	`error`	When
400	`invalid_period`	`from`/`to` are not dates, `to` is before `from`, or the period exceeds 366 days.
400	`invalid_shop`, `invalid_param`, …	A malformed parameter. Each API's page lists its own codes.
401	`unauthorized`	Missing, invalid or revoked key.
403	`forbidden`	The key does not cover one of the requested stores (with SmartBox and the AI assistant also language versions).
429	`rate_limited`	More than 120 requests per minute. Wait and retry.
502, 503	`upstream`, `unavailable`	A temporary outage on our side. Retry later.

Error messages are in Slovak; rely on the error code.

Versions and changes

The version is in the URL (/v1). We may add new fields at any time; existing fields and their meaning do not change within a version. We will tell you in advance about any new version.

The version is part of the API path (/api/stats/v1), not of the documentation's address: a page always describes the current version. Each API lists its changes on its own page: AI assistant, Smart Search, SmartBox.

API basics