Ingesta
El protocolo que usan los SDK para enviar eventos, trozos de grabación y capturas de página, para quien escribe su propio cliente.
Los SDK llaman a estos endpoints por ti. Lee esta página si escribes tu propio cliente, si envías eventos desde una plataforma sin SDK, o si quieres saber exactamente qué sale del navegador.
En Sypnia Cloud el servidor es https://ingest.sypnia.com. Un motor alojado por ti sirve las mismas rutas desde su propia URL base.
Autenticación
Los endpoints de ingesta reciben una llave de ingesta (spk_…). Es pública y solo de escritura: puede enviar datos y no puede leer nada. Envíala de una de dos formas:
- el encabezado
Authorization: Bearer spk_…, o - el parámetro
key=spk_…, paranavigator.sendBeacon, que no puede poner encabezados.
Un token de API (sps_…) se rechaza aquí con 403 wrong_credential, así un secreto nunca termina por error en un navegador.
Cuerpos
Todo cuerpo es JSON. Lo puedes comprimir con gzip: el motor detecta gzip por los dos primeros bytes (1f 8b), diga lo que diga el Content-Type, porque sendBeacon no puede poner Content-Encoding. Los límites se revisan después de descomprimir.
Límites
| Límite | Valor |
|---|---|
| Eventos en un lote | 200 |
| Cuerpo de un lote | 2 MiB después de descomprimir. El SDK del navegador mantiene un lote por debajo de 40.800 caracteres para que quepa en una petición keepalive |
| Cuerpo de un trozo de grabación o de una captura de página | 4.000.000 de bytes después de descomprimir |
| Trozos de grabación en una sesión | 720 (dos horas a un trozo cada 10 segundos) |
| Capturas de página en una sesión | 5, una por ruta (son la imagen que va debajo de un mapa de clics) |
| Pila de un error | 4.000 caracteres |
| Mensaje de un error | 500 caracteres |
| Etiqueta y contexto de un clic | 80 caracteres cada uno |
| Selector | 200 caracteres |
Las cadenas más largas se cortan, no se rechazan. Los eventos que no pasan la validación se descartan uno por uno y se cuentan en la respuesta; el resto del lote se guarda.
Reintentos
Reintenta una falla de red, 408, 429 y 5xx, con el mismo batch_id (eventos) o el mismo seq (grabación). Los dos son idempotentes: un lote o un trozo repetido se reemplaza a sí mismo. No reintentes ningún otro 4xx. Con 429, espera lo que diga Retry-After.
Cuando se llega a un límite
Nada se descarta en silencio. Cada respuesta dice cuántos eventos se guardaron y cuántos no, y por qué. Cuando el proyecto llega a un límite (el de un plan en Sypnia Cloud, una cuota que tú pusiste en tu motor), la respuesta trae slow_down: qué debe seguir enviando el SDK y hasta cuándo. Los SDK oficiales lo obedecen. El dueño del proyecto recibe una alerta al 80 % y al 100 %. Mira uso.
Orígenes
Un proyecto puede listar los orígenes que pueden enviar datos desde un navegador (settings.allowed_origins). Cuando la lista está vacía se acepta cualquier origen. Las peticiones sin encabezado Origin (servidores, apps móviles) siempre se aceptan.
Enviar un lote de eventos
/v1/ingest/events MotorNube Guarda hasta 200 eventos. La forma de cada evento está en el esquema de eventos (spec/events.schema.json); este endpoint solo define el sobre que los envuelve.
El motor valida cada evento por separado. Un evento válido se guarda; uno inválido se descarta y se cuenta en dropped, con la razón en dropped_reasons. Los campos que el motor no conoce se conservan, así un SDK más nuevo nunca rompe un motor más viejo. El motor le pone a cada evento el proyecto y la hora en que llegó, y nunca los toma de quien envía.
El entorno es distinto: solo tu app lo sabe, así que viene en el evento (env), y es production cuando el evento no trae ninguno. Un proyecto guarda hasta 20 nombres de entorno. Un evento que agregaría el número veintiuno se descarta y se cuenta en environment_limit, para que un error en tu código no cree entornos sin fin.
Envía batch_id y reutilízalo al reintentar: un lote que llega dos veces se guarda una sola vez.
Cuerpo
-
batch_idstring, hasta 64 caracteres opcionalUn id que quien envía elige para este lote, un UUID. Un reintento lo reutiliza: un lote que llega dos veces se guarda una.
-
sent_attimestamp opcionalCuándo salió el lote, según el reloj de quien envía, en ISO 8601 y UTC. El motor lo compara con su propio reloj para notar un dispositivo con la hora mal.
-
sdkobject opcionalQué SDK armó el lote.
-
sdk.namestring, hasta 40 caracteresEl nombre del paquete, por ejemplo
@sypnia/browser. -
sdk.versionstring, hasta 20 caracteresLa versión del paquete, por ejemplo
1.0.0. -
eventslista de object, hasta 200 elementos obligatorioLos eventos, en el orden en que ocurrieron. Máximo 200. Una lista vacía se acepta y no guarda nada.
Petición
curl -X POST "https://ingest.sypnia.com/v1/ingest/events" \
-H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
-H "Content-Type: application/json" \
--data @batch.jsonCuerpo de la petición
{
"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)"
}
]
}Los eventos de arriba están recortados para mostrar el sobre. El esquema de eventos lista cada campo de cada tipo de evento.
Respuesta: Todo guardado200
{
"accepted": 2,
"dropped": 0
}Respuesta: El proyecto llegó a su límite de eventos200
{
"accepted": 1,
"dropped": 1,
"dropped_reasons": {
"limit_reached": 1
},
"slow_down": {
"reason": "events_limit",
"send": "failures",
"replay": false,
"until": "2026-04-01T00:00:00Z"
}
}Errores
- 400
invalid_bodyEl cuerpo no es JSON, no es gzip válido, o
eventsno es una lista. - 400
too_many_eventsMás de 200 eventos en el lote. No se guarda nada. Divide el lote.
- 401
unauthorizedFalta la llave de ingesta, es desconocida o está revocada.
- 403
wrong_credentialSe envió un token de API o el token raíz. La ingesta solo recibe una llave de ingesta.
- 403
origin_not_allowedLa petición trae un
Originque no está enallowed_originsdel proyecto. - 413
payload_too_largeEl cuerpo pesa más de 2 MiB después de descomprimirlo.
- 429
rate_limitedDemasiadas peticiones desde esta dirección con esta llave. Espera lo que diga
Retry-Aftery envía el mismo lote otra vez. - 503
unavailableEl motor no pudo escribir en el almacenamiento. Reintenta con el mismo
batch_id.
Enviar un trozo de grabación
/v1/ingest/replay MotorNube Guarda un trozo de la grabación de una sesión. El SDK envía un trozo cada 10 segundos, o antes si el trozo pasa de 200 KB. seq empieza en 0 y sube de a uno por trozo; enviar el mismo seq otra vez reemplaza el trozo.
El motor no mira dentro de events: el enmascarado ocurre en el navegador, antes de enviar nada. Lo que sí hace el motor es rechazar un trozo cuya route coincide con una de las replay.blocked_routes del proyecto, así una ruta que apagaste sigue apagada aunque alguien tenga abierta una pestaña con un SDK viejo.
Cuerpo
-
sidstring obligatorioId de sesión: 32 caracteres hex aleatorios en minúscula, creados por el SDK del navegador y compartidos por todas las pestañas del mismo navegador (
localStorage, clavesypnia:session). Uno nuevo tras 30 minutos sin actividad, o cuando se identifica a otra persona. -
seqinteger, 0 a 719 obligatorioEl número del trozo en la sesión, desde 0. Enviar el mismo número otra vez reemplaza el trozo.
-
ts_startnumber opcionalHora del primer cambio grabado en el trozo, en milisegundos desde 1970-01-01 UTC.
-
ts_endnumber opcionalHora del último cambio grabado en el trozo.
-
routestring, hasta 500 caracteres opcionalLa ruta con los ids reemplazados por
:id, para que/orders/8841y/orders/8842sean una sola ruta. Un segmento se vuelve:idcuando es todo dígitos, un UUID, un texto hex de 16 caracteres o más, un token de 20 caracteres o más que contiene un dígito, o contiene%. -
urlstring, hasta 500 caracteres opcionalLa ruta de la página cuando se abrió el trozo.
-
vwnumber opcionalAncho de la ventana cuando se abrió el trozo.
-
vhnumber opcionalAlto de la ventana cuando se abrió el trozo.
-
fullboolean opcionalTrue cuando el trozo trae una copia completa de la página.
-
maskinteger, 1 a 9 opcionalQué reglas de enmascarado aplicó el SDK antes de enviar: 1 las de siempre (todo lo escrito se enmascara, el texto de la página como se ve, los elementos marcados se enmascaran o se dejan fuera), 2
maskAllText(además, todo el texto de la página). -
eventslista de object obligatorioLos cambios grabados, en el formato propio de la grabadora (eventos de rrweb). Opacos para el motor.
Petición
curl -X POST "https://ingest.sypnia.com/v1/ingest/replay?key=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
-H "Content-Type: application/json" \
--data-binary @chunk.json.gzCuerpo de la petición
{
"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
}
}
]
}Respuesta200
{
"stored": true
}Errores
- 400
invalid_bodyEl cuerpo no es JSON, o falta
sid,seqoevents, o están mal formados. - 401
unauthorizedFalta la llave de ingesta, es desconocida o está revocada.
- 403
not_recordableLa
routedel trozo está en lasreplay.blocked_routesdel proyecto. No reintentes. - 413
payload_too_largeEl cuerpo pesa más de 4.000.000 de bytes después de descomprimirlo.
- 422
session_fullLa sesión ya tiene 720 trozos. El SDK deja de grabar esta sesión.
- 429
limit_reachedEl proyecto llegó a su límite de grabaciones. La respuesta trae
slow_down. Los eventos se siguen aceptando.
Enviar una captura de página
/v1/ingest/snapshot MotorNube Guarda una captura de una página, con el mismo enmascarado que las grabaciones. Sobre ella se dibujan los mapas de clics. El SDK toma como máximo una por ruta en una sesión, en una parte de las sesiones (snapshots.sample_rate, 0.5 por defecto), dos segundos después de que la página queda quieta.
Cuerpo
-
sidstring obligatorioId de sesión: 32 caracteres hex aleatorios en minúscula, creados por el SDK del navegador y compartidos por todas las pestañas del mismo navegador (
localStorage, clavesypnia:session). Uno nuevo tras 30 minutos sin actividad, o cuando se identifica a otra persona. -
routestring, hasta 500 caracteres obligatorioLa ruta con los ids reemplazados por
:id, para que/orders/8841y/orders/8842sean una sola ruta. Un segmento se vuelve:idcuando es todo dígitos, un UUID, un texto hex de 16 caracteres o más, un token de 20 caracteres o más que contiene un dígito, o contiene%. -
urlstring, hasta 500 caracteres opcionalLa ruta de la página.
-
devstring opcionalClase de dispositivo del navegador que la tomó. Uno de:
mobile,tablet,desktop.Por defecto:
desktop -
vwnumber opcionalAncho de la ventana.
-
vhnumber opcionalAlto de la ventana.
-
phnumber opcionalAlto completo de la página, en píxeles.
-
tsnumber opcionalCuándo se tomó, en milisegundos desde 1970-01-01 UTC.
-
maskinteger, 1 a 9 opcionalQué reglas de enmascarado aplicó el SDK antes de enviar: 1 las de siempre (todo lo escrito se enmascara, el texto de la página como se ve, los elementos marcados se enmascaran o se dejan fuera), 2
maskAllText(además, todo el texto de la página). -
snapshotobject obligatorioEl árbol de la página, en el formato propio de la grabadora (una captura de rrweb). Opaco para el motor.
Petición
curl -X POST "https://ingest.sypnia.com/v1/ingest/snapshot?key=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
-H "Content-Type: application/json" \
--data-binary @snapshot.json.gzCuerpo de la petición
{
"sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
"route": "/checkout",
"url": "/checkout",
"dev": "desktop",
"vw": 1440,
"vh": 900,
"ph": 1630,
"ts": 1773311490000,
"mask": 1,
"snapshot": {
"type": 0,
"childNodes": [],
"id": 1
}
}Respuesta200
{
"stored": true
}Errores
- 400
invalid_bodyEl cuerpo no es JSON, o falta
sid,routeosnapshot, o están mal formados. - 403
not_recordableLa
routede la captura está en lasreplay.blocked_routesdel proyecto. - 413
payload_too_largeEl cuerpo pesa más de 4.000.000 de bytes después de descomprimirlo. El SDK descarta por su cuenta las capturas de más de 3 MB.
Leer lo que debe hacer el SDK
/v1/ingest/config MotorNube El SDK llama a este endpoint una vez por sesión para conocer las reglas de grabación del proyecto, así las puedes cambiar sin volver a publicar tu app. Pasa la persona y la cuenta cuando las sepas: una regla de «grabar siempre» para cualquiera de las dos pone replay.mode en record.
replay.mode es la decisión para esta sesión:
| Modo | Qué hace el SDK |
|---|---|
record | Sube la grabación desde el comienzo. Se elige para la parte de sample_rate y para las reglas de «grabar siempre» |
buffer | Guarda en memoria los últimos 30 segundos y los sube, junto con todo lo que sigue, en el momento en que la sesión tiene un error, un clic de rabia o un clic muerto. Así es como toda sesión con un error queda con grabación |
off | No graba nada. El proyecto apagó la grabación, o llegó a su límite de grabaciones |
Si esta llamada falla, el SDK usa buffer.
Parámetros de consulta
-
sidstring obligatorioEl id de la sesión. La decisión es estable para una sesión: el mismo
sidsiempre recibe la misma respuesta. -
personstring, hasta 128 caracteres opcionalEl id de la persona, si tu app la identificó.
-
accountstring, hasta 128 caracteres opcionalEl id de la cuenta, si tu app envió una.
Petición
curl "https://ingest.sypnia.com/v1/ingest/config?sid=8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0&person=u_1042" \
-H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e"Respuesta200
{
"replay": {
"mode": "buffer",
"sample_rate": 0.1,
"mask_all_text": false,
"blocked_routes": [
"/account/cards"
]
},
"snapshots": {
"sample_rate": 0.5
},
"slow_down": null
}Cargar el SDK del navegador
/v1/sdk.js MotorNube El SDK del navegador en un solo script, para una página sin paso de build. Es el archivo que carga la etiqueta script: <script async src="https://ingest.sypnia.com/v1/sdk.js" data-project="spk_…"></script>. Es el mismo código del paquete de npm @sypnia/browser, armado para correr directo. Lo sirve el propio motor, así que un motor alojado por ti no necesita otro servidor: usa <tu URL base>/v1/sdk.js.
No necesita credencial y se puede cargar desde cualquier origen. La llave de ingesta no va en la petición: el script la lee de su propio atributo data-project, o de tu llamada a init.
Versiones. Sin v recibes el SDK más nuevo de la versión mayor 1 que tenga el motor. Dentro de una versión mayor el SDK solo agrega, igual que el contrato de eventos, así que una página nunca tiene que cambiar su etiqueta. Sypnia Cloud tiene todas las versiones 1.x publicadas; un motor alojado por ti tiene aquella con la que salió. Para fijar una versión, pídela con v.
Caché. El archivo sin versión fija se guarda en caché una hora (Cache-Control: public, max-age=3600, stale-while-revalidate=86400) y trae un ETag. Una versión fija nunca cambia y se guarda un año (immutable). El encabezado de respuesta Sypnia-SDK-Version dice qué versión se sirvió.
La grabadora para grabaciones y capturas de página es un segundo archivo, /v1/sdk-recorder.js, que el SDK carga por su cuenta cuando el navegador está desocupado, con las mismas reglas. Tú nunca lo referencias.
Parámetros de consulta
-
vstring opcionalUna versión exacta del SDK, como
1.4.2, para fijar el archivo. Sin ella se sirve la 1.x más nueva.
Petición
curl -I "https://ingest.sypnia.com/v1/sdk.js"Respuesta200
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: *Errores
- 404
not_foundvnombra una versión que este motor no tiene. Un motor alojado por ti solo tiene la versión con la que salió.
Los errores que cualquier endpoint puede responder (401, 403, 429, 500, 503) están en Errores, límites, paginación.