Docs

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.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Autenticación
  2. Cuerpos
  3. Límites
  4. Reintentos
  5. Cuando se llega a un límite
  6. Orígenes
  7. Enviar un lote de eventos
  8. Enviar un trozo de grabación
  9. Enviar una captura de página
  10. Leer lo que debe hacer el SDK
  11. Cargar el SDK del navegador

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_…, para navigator.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ímiteValor
Eventos en un lote200
Cuerpo de un lote2 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ágina4.000.000 de bytes después de descomprimir
Trozos de grabación en una sesión720 (dos horas a un trozo cada 10 segundos)
Capturas de página en una sesión5, una por ruta (son la imagen que va debajo de un mapa de clics)
Pila de un error4.000 caracteres
Mensaje de un error500 caracteres
Etiqueta y contexto de un clic80 caracteres cada uno
Selector200 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

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

Autenticación
Llave de ingesta

Cuerpo

  • batch_id
    string, hasta 64 caracteres opcional

    Un 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_at
    timestamp opcional

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

  • sdk
    object opcional

    Qué SDK armó el lote.

  • sdk.name
    string, hasta 40 caracteres

    El nombre del paquete, por ejemplo @sypnia/browser.

  • sdk.version
    string, hasta 20 caracteres

    La versión del paquete, por ejemplo 1.0.0.

  • events
    lista de object, hasta 200 elementos obligatorio

    Los eventos, en el orden en que ocurrieron. Máximo 200. Una lista vacía se acepta y no guarda nada.

Petición

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

Cuerpo de la petición

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)"
    }
  ]
}

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

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

Respuesta: El proyecto llegó a su límite de eventos200

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

Errores

  • 400invalid_body

    El cuerpo no es JSON, no es gzip válido, o events no es una lista.

  • 400too_many_events

    Más de 200 eventos en el lote. No se guarda nada. Divide el lote.

  • 401unauthorized

    Falta la llave de ingesta, es desconocida o está revocada.

  • 403wrong_credential

    Se envió un token de API o el token raíz. La ingesta solo recibe una llave de ingesta.

  • 403origin_not_allowed

    La petición trae un Origin que no está en allowed_origins del proyecto.

  • 413payload_too_large

    El cuerpo pesa más de 2 MiB después de descomprimirlo.

  • 429rate_limited

    Demasiadas peticiones desde esta dirección con esta llave. Espera lo que diga Retry-After y envía el mismo lote otra vez.

  • 503unavailable

    El motor no pudo escribir en el almacenamiento. Reintenta con el mismo batch_id.

Enviar un trozo de grabación

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

Autenticación
Llave de ingesta

Cuerpo

  • sid
    string obligatorio

    Id 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, clave sypnia:session). Uno nuevo tras 30 minutos sin actividad, o cuando se identifica a otra persona.

  • seq
    integer, 0 a 719 obligatorio

    El número del trozo en la sesión, desde 0. Enviar el mismo número otra vez reemplaza el trozo.

  • ts_start
    number opcional

    Hora del primer cambio grabado en el trozo, en milisegundos desde 1970-01-01 UTC.

  • ts_end
    number opcional

    Hora del último cambio grabado en el trozo.

  • route
    string, hasta 500 caracteres opcional

    La ruta con los ids reemplazados por :id, para que /orders/8841 y /orders/8842 sean una sola ruta. Un segmento se vuelve :id cuando 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 %.

  • url
    string, hasta 500 caracteres opcional

    La ruta de la página cuando se abrió el trozo.

  • vw
    number opcional

    Ancho de la ventana cuando se abrió el trozo.

  • vh
    number opcional

    Alto de la ventana cuando se abrió el trozo.

  • full
    boolean opcional

    True cuando el trozo trae una copia completa de la página.

  • mask
    integer, 1 a 9 opcional

    Qué 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).

  • events
    lista de object obligatorio

    Los cambios grabados, en el formato propio de la grabadora (eventos de rrweb). Opacos para el motor.

Petición

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

Cuerpo de la petición

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

Respuesta200

JSON
{
  "stored": true
}

Errores

  • 400invalid_body

    El cuerpo no es JSON, o falta sid, seq o events, o están mal formados.

  • 401unauthorized

    Falta la llave de ingesta, es desconocida o está revocada.

  • 403not_recordable

    La route del trozo está en las replay.blocked_routes del proyecto. No reintentes.

  • 413payload_too_large

    El cuerpo pesa más de 4.000.000 de bytes después de descomprimirlo.

  • 422session_full

    La sesión ya tiene 720 trozos. El SDK deja de grabar esta sesión.

  • 429limit_reached

    El proyecto llegó a su límite de grabaciones. La respuesta trae slow_down. Los eventos se siguen aceptando.

Enviar una captura de página

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

Autenticación
Llave de ingesta

Cuerpo

  • sid
    string obligatorio

    Id 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, clave sypnia:session). Uno nuevo tras 30 minutos sin actividad, o cuando se identifica a otra persona.

  • route
    string, hasta 500 caracteres obligatorio

    La ruta con los ids reemplazados por :id, para que /orders/8841 y /orders/8842 sean una sola ruta. Un segmento se vuelve :id cuando 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 %.

  • url
    string, hasta 500 caracteres opcional

    La ruta de la página.

  • dev
    string opcional

    Clase de dispositivo del navegador que la tomó. Uno de: mobile, tablet, desktop.

    Por defecto: desktop

  • vw
    number opcional

    Ancho de la ventana.

  • vh
    number opcional

    Alto de la ventana.

  • ph
    number opcional

    Alto completo de la página, en píxeles.

  • ts
    number opcional

    Cuándo se tomó, en milisegundos desde 1970-01-01 UTC.

  • mask
    integer, 1 a 9 opcional

    Qué 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).

  • snapshot
    object obligatorio

    El árbol de la página, en el formato propio de la grabadora (una captura de rrweb). Opaco para el motor.

Petición

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

Cuerpo de la petición

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

Respuesta200

JSON
{
  "stored": true
}

Errores

  • 400invalid_body

    El cuerpo no es JSON, o falta sid, route o snapshot, o están mal formados.

  • 403not_recordable

    La route de la captura está en las replay.blocked_routes del proyecto.

  • 413payload_too_large

    El 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

GET /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:

ModoQué hace el SDK
recordSube la grabación desde el comienzo. Se elige para la parte de sample_rate y para las reglas de «grabar siempre»
bufferGuarda 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
offNo graba nada. El proyecto apagó la grabación, o llegó a su límite de grabaciones

Si esta llamada falla, el SDK usa buffer.

Autenticación
Llave de ingesta

Parámetros de consulta

  • sid
    string obligatorio

    El id de la sesión. La decisión es estable para una sesión: el mismo sid siempre recibe la misma respuesta.

  • person
    string, hasta 128 caracteres opcional

    El id de la persona, si tu app la identificó.

  • account
    string, hasta 128 caracteres opcional

    El id de la cuenta, si tu app envió una.

Petición

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

Respuesta200

JSON
{
  "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

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

Autenticación
Ninguna. Es público

Parámetros de consulta

  • v
    string opcional

    Una 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

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

Respuesta200

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

Errores

  • 404not_found

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

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar