Docs

Ingest

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

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Authentication
  2. Bodies
  3. Limits
  4. Retries
  5. When a limit is reached
  6. Origins
  7. Send a batch of events
  8. Send a replay chunk
  9. Send a page snapshot
  10. Read what the SDK should do
  11. Load the browser SDK

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

LimitValue
Events in one batch200
Batch body2 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 body4,000,000 bytes after decompression
Replay chunks in one session720 (two hours at one chunk every 10 seconds)
Page snapshots in one session5, one per route (they are the picture under a click map)
Error stack4,000 characters
Error message500 characters
Click label and click context80 characters each
Selector200 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

POST /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.

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

Terminal
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 stored200

JSON
{
  "accepted": 2,
  "dropped": 0
}

Response: The project reached its events limit200

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

  • 400invalid_body

    The body is not JSON, not valid gzip, or events is not a list.

  • 400too_many_events

    More than 200 events in the batch. Nothing is stored. Split the batch.

  • 401unauthorized

    The ingest key is missing, unknown or revoked.

  • 403wrong_credential

    An API token or the root token was sent. Ingest only takes an ingest key.

  • 403origin_not_allowed

    The request has an Origin that is not in the project’s allowed_origins.

  • 413payload_too_large

    The body is larger than 2 MiB after decompression.

  • 429rate_limited

    Too many requests from this address with this key. Wait for Retry-After and send the same batch again.

  • 503unavailable

    The engine could not write to storage. Retry with the same batch_id.

Send a replay chunk

POST /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.

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

Terminal
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
      }
    }
  ]
}

Response200

JSON
{
  "stored": true
}

Errors

  • 400invalid_body

    The body is not JSON or sid, seq or events is missing or malformed.

  • 401unauthorized

    The ingest key is missing, unknown or revoked.

  • 403not_recordable

    The chunk’s route is in the project’s replay.blocked_routes. Do not retry.

  • 413payload_too_large

    The body is larger than 4,000,000 bytes after decompression.

  • 422session_full

    The session already has 720 chunks. The SDK stops recording this session.

  • 429limit_reached

    The project reached its replays limit. The answer carries slow_down. Events are still accepted.

Send a page snapshot

POST /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.

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

    Device class of the browser that took it. One of: mobile, tablet, desktop.

    Default: 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

Terminal
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
  }
}

Response200

JSON
{
  "stored": true
}

Errors

  • 400invalid_body

    The body is not JSON or sid, route or snapshot is missing or malformed.

  • 403not_recordable

    The snapshot’s route is in the project’s replay.blocked_routes.

  • 413payload_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 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:

ModeWhat the SDK does
recordUploads the recording from the start. Chosen for the share in sample_rate and for «always record» rules
bufferKeeps 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
offRecords 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

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

Response200

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

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

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

Response200

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

  • 404not_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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close