Ingest
The protocol the SDKs use to send events, replay chunks and page snapshots, for anyone writing their own client.
The SDKs call these endpoints for you. Read this page if you write your own client, send events from a platform without an SDK, or want to know exactly what leaves the browser.
On Sypnia Cloud the host is https://ingest.sypnia.com. A self-hosted engine serves the same paths from its
own base URL.
Authentication
Ingest endpoints take an ingest key (spk_…). It is public and write-only: it can send data and read
nothing. Send it in one of two ways:
- the header
Authorization: Bearer spk_…, or - the query parameter
key=spk_…, fornavigator.sendBeacon, which cannot set headers.
An API token (sps_…) is rejected here with 403 wrong_credential, so a secret never ends up in a browser by
mistake.
Bodies
Every body is JSON. You may gzip it: the engine detects gzip from the first two bytes (1f 8b), whatever the
Content-Type says, because sendBeacon cannot set Content-Encoding. Limits are checked after
decompression.
Limits
| Limit | Value |
|---|---|
| Events in one batch | 200 |
| Batch body | 2 MiB after decompression. The browser SDK keeps a batch under 40,800 characters so it fits in a keepalive request |
| Replay chunk or page snapshot body | 4,000,000 bytes after decompression |
| Replay chunks in one session | 720 (two hours at one chunk every 10 seconds) |
| Page snapshots in one session | 5, one per route (they are the picture under a click map) |
| Error stack | 4,000 characters |
| Error message | 500 characters |
| Click label and click context | 80 characters each |
| Selector | 200 characters |
Longer strings are cut, not rejected. Events that fail validation are dropped one by one and counted in the answer; the rest of the batch is stored.
Retries
Retry a network failure, 408, 429 and 5xx, with the same batch_id (events) or the same seq
(replay). Both are idempotent: a repeated batch or chunk replaces itself. Do not retry any other 4xx.
On 429 wait for Retry-After.
When a limit is reached
Nothing is dropped silently. Every answer says how many events were stored and how many were not, and why.
When the project reaches a limit (a plan limit on Sypnia Cloud, a quota you set on your own engine), the answer
carries slow_down: what the SDK should keep sending and until when. The official SDKs obey it. The project’s
owner gets an alert at 80 % and at 100 %. See usage.
Origins
A project can list the origins allowed to send browser data (settings.allowed_origins). When the list is
empty, any origin is accepted. Requests without an Origin header (servers, mobile apps) are always accepted.
Send a batch of events
/v1/ingest/events EngineCloud Stores up to 200 events. The shape of each event is the event schema
(spec/events.schema.json); this endpoint defines only the envelope around them.
The engine validates each event on its own. A valid event is stored; an invalid one is dropped and counted
in dropped, with the reason in dropped_reasons. Fields the engine does not know are kept, so a newer SDK
never breaks an older engine. The engine stamps every event with the project and the time it arrived, and
never takes those from the sender.
The environment is different: only your app knows it, so it comes from the event (env), and it is
production when the event has none. A project keeps up to 20 environment names. An event that would add a
twenty-first is dropped and counted under environment_limit, so a mistake in your code cannot create
environments without end.
Send batch_id and reuse it when you retry: a batch that arrives twice is stored once.
Body
-
batch_idstring, up to 64 characters optionalAn id the sender chooses for this batch, a UUID. A retry reuses it: a batch that arrives twice is stored once.
-
sent_attimestamp optionalWhen the batch left, by the sender’s clock, ISO 8601 in UTC. The engine compares it with its own clock to notice a device whose clock is wrong.
-
sdkobject optionalWhich SDK built the batch.
-
sdk.namestring, up to 40 charactersThe package name, for example
@sypnia/browser. -
sdk.versionstring, up to 20 charactersThe package version, for example
1.0.0. -
eventsarray of object, up to 200 items requiredThe events, in the order they happened. At most 200. An empty list is accepted and stores nothing.
Request
curl -X POST "https://ingest.sypnia.com/v1/ingest/events" \
-H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
-H "Content-Type: application/json" \
--data @batch.jsonRequest body
{
"batch_id": "0b9f6c3e-2a41-4d7e-9c1b-6f2e8a4d7c10",
"sent_at": "2026-03-12T10:31:48Z",
"sdk": {
"name": "@sypnia/browser",
"version": "1.0.0"
},
"events": [
{
"v": 1,
"type": "click",
"ts": 1773311503000,
"sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
"url": "/checkout",
"route": "/checkout",
"sel": "#pay-button",
"txt": "Pay $64.00",
"crole": "button",
"ctx": "Your order"
},
{
"v": 1,
"type": "error",
"ts": 1773311507004,
"sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
"url": "/checkout",
"route": "/checkout",
"name": "ApiError",
"msg": "POST /api/checkout failed with 400 (amount_required)"
}
]
}The events above are shortened to show the envelope. The event schema lists every field of every event type.
Response: Everything stored200
{
"accepted": 2,
"dropped": 0
}Response: The project reached its events limit200
{
"accepted": 1,
"dropped": 1,
"dropped_reasons": {
"limit_reached": 1
},
"slow_down": {
"reason": "events_limit",
"send": "failures",
"replay": false,
"until": "2026-04-01T00:00:00Z"
}
}Errors
- 400
invalid_bodyThe body is not JSON, not valid gzip, or
eventsis not a list. - 400
too_many_eventsMore than 200 events in the batch. Nothing is stored. Split the batch.
- 401
unauthorizedThe ingest key is missing, unknown or revoked.
- 403
wrong_credentialAn API token or the root token was sent. Ingest only takes an ingest key.
- 403
origin_not_allowedThe request has an
Originthat is not in the project’sallowed_origins. - 413
payload_too_largeThe body is larger than 2 MiB after decompression.
- 429
rate_limitedToo many requests from this address with this key. Wait for
Retry-Afterand send the same batch again. - 503
unavailableThe engine could not write to storage. Retry with the same
batch_id.
Send a replay chunk
/v1/ingest/replay EngineCloud Stores one piece of a session’s recording. The SDK sends a chunk every 10 seconds, or sooner when the chunk
passes 200 KB. seq starts at 0 and grows by one per chunk; sending the same seq again replaces the chunk.
The engine does not look inside events: masking happens in the browser, before anything is sent. The engine
does refuse a chunk whose route matches one of the project’s replay.blocked_routes, so a route you
switched off stays off even with an old SDK in someone’s open tab.
Body
-
sidstring requiredSession id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (
localStorage, keysypnia:session). A new one after 30 minutes without activity, or when another person is identified. -
seqinteger, 0 to 719 requiredThe piece’s number in the session, from 0. Sending the same number again replaces the piece.
-
ts_startnumber optionalTime of the first recorded change in the piece, in milliseconds since 1970-01-01 UTC.
-
ts_endnumber optionalTime of the last recorded change in the piece.
-
routestring, up to 500 characters optionalThe path with ids replaced by
:id, so/orders/8841and/orders/8842are one route. A segment becomes:idwhen it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains%. -
urlstring, up to 500 characters optionalThe page’s path when the piece was opened.
-
vwnumber optionalViewport width when the piece was opened.
-
vhnumber optionalViewport height when the piece was opened.
-
fullboolean optionalTrue when the piece holds a full copy of the page.
-
maskinteger, 1 to 9 optionalWhich masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2
maskAllText(also every text of the page). -
eventsarray of object requiredThe recorded changes, in the recorder’s own format (rrweb events). Opaque to the engine.
Request
curl -X POST "https://ingest.sypnia.com/v1/ingest/replay?key=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
-H "Content-Type: application/json" \
--data-binary @chunk.json.gzRequest body
{
"sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
"seq": 3,
"ts_start": 1773311497000,
"ts_end": 1773311507000,
"route": "/checkout",
"url": "/checkout",
"vw": 1440,
"vh": 900,
"full": false,
"mask": 1,
"events": [
{
"type": 3,
"timestamp": 1773311503000,
"data": {
"source": 2,
"type": 2,
"id": 418,
"x": 912,
"y": 640
}
}
]
}Response200
{
"stored": true
}Errors
- 400
invalid_bodyThe body is not JSON or
sid,seqoreventsis missing or malformed. - 401
unauthorizedThe ingest key is missing, unknown or revoked.
- 403
not_recordableThe chunk’s
routeis in the project’sreplay.blocked_routes. Do not retry. - 413
payload_too_largeThe body is larger than 4,000,000 bytes after decompression.
- 422
session_fullThe session already has 720 chunks. The SDK stops recording this session.
- 429
limit_reachedThe project reached its replays limit. The answer carries
slow_down. Events are still accepted.
Send a page snapshot
/v1/ingest/snapshot EngineCloud Stores a snapshot of one page, with the same masking as replays. Click maps are drawn over it. The SDK takes
at most one per route in a session, for a share of sessions (snapshots.sample_rate, default 0.5), two seconds
after the page is quiet.
Body
-
sidstring requiredSession id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (
localStorage, keysypnia:session). A new one after 30 minutes without activity, or when another person is identified. -
routestring, up to 500 characters requiredThe path with ids replaced by
:id, so/orders/8841and/orders/8842are one route. A segment becomes:idwhen it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains%. -
urlstring, up to 500 characters optionalThe page’s path.
-
devstring optionalDevice class of the browser that took it. One of:
mobile,tablet,desktop.Default:
desktop -
vwnumber optionalViewport width.
-
vhnumber optionalViewport height.
-
phnumber optionalFull height of the page, in pixels.
-
tsnumber optionalWhen it was taken, in milliseconds since 1970-01-01 UTC.
-
maskinteger, 1 to 9 optionalWhich masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2
maskAllText(also every text of the page). -
snapshotobject requiredThe page’s tree, in the recorder’s own format (an rrweb snapshot). Opaque to the engine.
Request
curl -X POST "https://ingest.sypnia.com/v1/ingest/snapshot?key=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
-H "Content-Type: application/json" \
--data-binary @snapshot.json.gzRequest body
{
"sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
"route": "/checkout",
"url": "/checkout",
"dev": "desktop",
"vw": 1440,
"vh": 900,
"ph": 1630,
"ts": 1773311490000,
"mask": 1,
"snapshot": {
"type": 0,
"childNodes": [],
"id": 1
}
}Response200
{
"stored": true
}Errors
- 400
invalid_bodyThe body is not JSON or
sid,routeorsnapshotis missing or malformed. - 403
not_recordableThe snapshot’s
routeis in the project’sreplay.blocked_routes. - 413
payload_too_largeThe body is larger than 4,000,000 bytes after decompression. The SDK drops snapshots above 3 MB by itself.
Read what the SDK should do
/v1/ingest/config EngineCloud The SDK calls this once per session to learn the project’s recording rules, so you can change them without
shipping your app again. Pass the person and the account when you know them: an «always record» rule for
either one sets replay.mode to record.
replay.mode is the decision for this session:
| Mode | What the SDK does |
|---|---|
record | Uploads the recording from the start. Chosen for the share in sample_rate and for «always record» rules |
buffer | Keeps the last 30 seconds in memory and uploads them, and everything after, the moment the session has an error, a rage click or a dead click. This is how every session with an error gets a replay |
off | Records nothing. The project switched replay off, or reached its replays limit |
If this call fails, the SDK uses buffer.
Query parameters
-
sidstring requiredThe session id. The decision is stable for a session, the same
sidalways gets the same answer. -
personstring, up to 128 characters optionalThe person’s id, if your app identified them.
-
accountstring, up to 128 characters optionalThe account’s id, if your app sent one.
Request
curl "https://ingest.sypnia.com/v1/ingest/config?sid=8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0&person=u_1042" \
-H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e"Response200
{
"replay": {
"mode": "buffer",
"sample_rate": 0.1,
"mask_all_text": false,
"blocked_routes": [
"/account/cards"
]
},
"snapshots": {
"sample_rate": 0.5
},
"slow_down": null
}Load the browser SDK
/v1/sdk.js EngineCloud The browser SDK as one script, for a page with no build step. It is the file the script tag loads:
<script async src="https://ingest.sypnia.com/v1/sdk.js" data-project="spk_…"></script>. It is the same
code as the npm package @sypnia/browser, built to run directly. The engine serves it itself, so a
self-hosted engine needs no other host: use <your base URL>/v1/sdk.js.
It needs no credential and can be loaded from any origin. The ingest key is not part of the request: the
script reads it from its own data-project attribute, or from your call to init.
Versions. Without v, you get the newest SDK of major version 1 that the engine carries. Inside a major
version the SDK only adds, as the event contract does, so a page never has to change its tag. Sypnia Cloud
carries every published 1.x version; a self-hosted engine carries the one it was released with. To pin a
version, ask for it with v.
Caching. The unpinned file is cached for one hour (Cache-Control: public, max-age=3600, stale-while-revalidate=86400) and has an ETag. A pinned version never changes and is cached for a year
(immutable). The response header Sypnia-SDK-Version says which version was served.
The recorder for replays and page snapshots is a second file, /v1/sdk-recorder.js, that the SDK loads by
itself when the browser is idle, with the same rules. You never reference it.
Query parameters
-
vstring optionalAn exact SDK version, such as
1.4.2, to pin the file. Without it the newest 1.x is served.
Request
curl -I "https://ingest.sypnia.com/v1/sdk.js"Response200
HTTP/2 200
content-type: text/javascript; charset=utf-8
cache-control: public, max-age=3600, stale-while-revalidate=86400
etag: "1.4.2-9f3c2a"
sypnia-sdk-version: 1.4.2
access-control-allow-origin: *Errors
- 404
not_foundvnames a version this engine does not carry. A self-hosted engine carries only the version it was released with.
The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.