# Ingest

> The protocol the SDKs use to send events, replay chunks and page snapshots, for anyone writing their own client.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/ingest/

For agents: Reference of the Ingest endpoints of the Sypnia HTTP API: parameters, response shapes, examples and errors.

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_…`, for `navigator.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](https://docs.sypnia.com/api/projects-keys-and-tokens).

## 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

`POST /v1/ingest/events` \[Engine, Cloud]

Stores up to 200 events. The shape of each event is the [event schema](https://docs.sypnia.com/reference/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.

**Authentication:** Ingest key

**Body:**

- `batch_id` (string, up to 64 characters, optional): An id the sender chooses for this batch, a UUID. A retry reuses it: a batch that arrives twice is stored once.
- `sent_at` (timestamp, optional): When 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.
- `sdk` (object, optional): Which SDK built the batch.
- `sdk.name` (string, up to 40 characters): The package name, for example `@sypnia/browser`.
- `sdk.version` (string, up to 20 characters): The package version, for example `1.0.0`.
- `events` (array of object, up to 200 items, required): The events, in the order they happened. At most 200. An empty list is accepted and stores nothing.

**Request:**

```bash
curl -X POST "https://ingest.sypnia.com/v1/ingest/events" \
  -H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  --data @batch.json
```

**Request body:**

```json
{
  "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 stored (200):**

```json
{
  "accepted": 2,
  "dropped": 0
}
```

**Response: The project reached its events limit (200):**

```json
{
  "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_body`: The body is not JSON, not valid gzip, or `events` is not a list.
- `400` `too_many_events`: More than 200 events in the batch. Nothing is stored. Split the batch.
- `401` `unauthorized`: The ingest key is missing, unknown or revoked.
- `403` `wrong_credential`: An API token or the root token was sent. Ingest only takes an ingest key.
- `403` `origin_not_allowed`: The request has an `Origin` that is not in the project's `allowed_origins`.
- `413` `payload_too_large`: The body is larger than 2 MiB after decompression.
- `429` `rate_limited`: Too many requests from this address with this key. Wait for `Retry-After` and send the same batch again.
- `503` `unavailable`: The engine could not write to storage. Retry with the same `batch_id`.

## Send a replay chunk

`POST /v1/ingest/replay` \[Engine, Cloud]

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.

**Authentication:** Ingest key

**Body:**

- `sid` (string, required): Session id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (`localStorage`, key `sypnia:session`). A new one after 30 minutes without activity, or when another person is identified.
- `seq` (integer, 0 to 719, required): The piece's number in the session, from 0. Sending the same number again replaces the piece.
- `ts_start` (number, optional): Time of the first recorded change in the piece, in milliseconds since 1970-01-01 UTC.
- `ts_end` (number, optional): Time of the last recorded change in the piece.
- `route` (string, up to 500 characters, optional): The path with ids replaced by `:id`, so `/orders/8841` and `/orders/8842` are one route. A segment becomes `:id` when 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 `%`.
- `url` (string, up to 500 characters, optional): The page's path when the piece was opened.
- `vw` (number, optional): Viewport width when the piece was opened.
- `vh` (number, optional): Viewport height when the piece was opened.
- `full` (boolean, optional): True when the piece holds a full copy of the page.
- `mask` (integer, 1 to 9, optional): Which 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).
- `events` (array of object, required): The recorded changes, in the recorder's own format (rrweb events). Opaque to the engine.

**Request:**

```bash
curl -X POST "https://ingest.sypnia.com/v1/ingest/replay?key=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  --data-binary @chunk.json.gz
```

**Request body:**

```json
{
  "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
      }
    }
  ]
}
```

**Response (200):**

```json
{
  "stored": true
}
```

**Errors:**

- `400` `invalid_body`: The body is not JSON or `sid`, `seq` or `events` is missing or malformed.
- `401` `unauthorized`: The ingest key is missing, unknown or revoked.
- `403` `not_recordable`: The chunk's `route` is in the project's `replay.blocked_routes`. Do not retry.
- `413` `payload_too_large`: The body is larger than 4,000,000 bytes after decompression.
- `422` `session_full`: The session already has 720 chunks. The SDK stops recording this session.
- `429` `limit_reached`: The project reached its replays limit. The answer carries `slow_down`. Events are still accepted.

## Send a page snapshot

`POST /v1/ingest/snapshot` \[Engine, Cloud]

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.

**Authentication:** Ingest key

**Body:**

- `sid` (string, required): Session id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (`localStorage`, key `sypnia:session`). A new one after 30 minutes without activity, or when another person is identified.
- `route` (string, up to 500 characters, required): The path with ids replaced by `:id`, so `/orders/8841` and `/orders/8842` are one route. A segment becomes `:id` when 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 `%`.
- `url` (string, up to 500 characters, optional): The page's path.
- `dev` (string, optional, default `desktop`): Device class of the browser that took it. One of: `mobile`, `tablet`, `desktop`.
- `vw` (number, optional): Viewport width.
- `vh` (number, optional): Viewport height.
- `ph` (number, optional): Full height of the page, in pixels.
- `ts` (number, optional): When it was taken, in milliseconds since 1970-01-01 UTC.
- `mask` (integer, 1 to 9, optional): Which 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).
- `snapshot` (object, required): The page's tree, in the recorder's own format (an rrweb snapshot). Opaque to the engine.

**Request:**

```bash
curl -X POST "https://ingest.sypnia.com/v1/ingest/snapshot?key=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  --data-binary @snapshot.json.gz
```

**Request body:**

```json
{
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "route": "/checkout",
  "url": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "ph": 1630,
  "ts": 1773311490000,
  "mask": 1,
  "snapshot": {
    "type": 0,
    "childNodes": [],
    "id": 1
  }
}
```

**Response (200):**

```json
{
  "stored": true
}
```

**Errors:**

- `400` `invalid_body`: The body is not JSON or `sid`, `route` or `snapshot` is missing or malformed.
- `403` `not_recordable`: The snapshot's `route` is in the project's `replay.blocked_routes`.
- `413` `payload_too_large`: The 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

`GET /v1/ingest/config` \[Engine, Cloud]

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`.

**Authentication:** Ingest key

**Query parameters:**

- `sid` (string, required): The session id. The decision is stable for a session, the same `sid` always gets the same answer.
- `person` (string, up to 128 characters, optional): The person's id, if your app identified them.
- `account` (string, up to 128 characters, optional): The account's id, if your app sent one.

**Request:**

```bash
curl "https://ingest.sypnia.com/v1/ingest/config?sid=8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0&person=u_1042" \
  -H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e"
```

**Response (200):**

```json
{
  "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

`GET /v1/sdk.js` \[Engine, Cloud]

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.

**Authentication:** None. Public

**Query parameters:**

- `v` (string, optional): An exact SDK version, such as `1.4.2`, to pin the file. Without it the newest 1.x is served.

**Request:**

```bash
curl -I "https://ingest.sypnia.com/v1/sdk.js"
```

**Response (200):**

```http
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_found`: `v` names 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](https://docs.sypnia.com/api/errors-limits-pagination).
