Resumen y autenticación
La URL base, los tres tipos de credencial y lo que puede hacer cada uno, y los tres endpoints que cubren todo un proyecto.
Motor Nube La API de Sypnia es una sola API HTTP para el motor de código abierto y para Sypnia Cloud. Sypnia Cloud es el mismo motor, corrido por nosotros, así que un endpoint se comporta igual en los dos. Los pocos que existen solo en uno llevan una insignia.
Todo lo que muestran la app, la Consola, el servidor MCP y la CLI sale de esta API. Su contrato legible por máquinas es spec/openapi.yaml, en el repositorio de la documentación (OpenAPI 3.1).
URL base
| Dónde | Leer y administrar | Enviar datos (ingesta, OTLP) |
|---|---|---|
| Sypnia Cloud | https://api.sypnia.com/v1 | https://ingest.sypnia.com/v1 |
| Motor alojado por ti | <tu URL base>/v1 | <tu URL base>/v1 |
Un motor alojado por ti sirve todo desde la única dirección que pusiste en SYPNIA_BASE_URL, con las mismas rutas. Los ejemplos de esta referencia usan las direcciones de Sypnia Cloud; cambia el servidor para usarlos contra tu motor.
Las peticiones y las respuestas son JSON en UTF-8. Envía Content-Type: application/json cuando haya cuerpo. En Sypnia Cloud solo se acepta HTTPS.
Autenticación
Envía la credencial en el encabezado Authorization:
curl https://api.sypnia.com/v1/problems \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Hay tres tipos de credencial. El motor no tiene usuarios ni contraseñas.
| Credencial | Cómo se ve | ¿Secreta? | Qué puede hacer | Dónde existe |
|---|---|---|---|---|
| Llave de ingesta | spk_ y 32 caracteres hexadecimales | No. Va dentro de tu app | Enviar datos, y nada más. Solo la aceptan los endpoints de ingesta y de OTLP | Motor y nube |
| Token de API | sps_ y 40 caracteres | Sí | Leer y administrar un proyecto, dentro de sus permisos | Motor y nube |
| Token raíz | Cualquier cadena de 32 caracteres o más que tú elijas | Sí | Todo, en todos los proyectos del motor | Solo en el motor. Se define con SYPNIA_ROOT_TOKEN |
Permisos de un token de API
| Permiso | Qué permite |
|---|---|
read | Leer todo salvo el contenido de las grabaciones. Sus únicas escrituras son marcas reversibles que quedan registradas con el nombre del token: resolver o reabrir un problema, marcar una alerta como vista, cambiar el estado de una sugerencia |
replay | Traer grabaciones y capturas de página. Muestran la página como la vio la persona, por eso este permiso va aparte |
admin | Todo lo que cambia el proyecto: llaves, tokens, ajustes, versiones y source maps, comprobaciones de disponibilidad, reglas de alerta, webhooks, ignorar un problema, borrar datos, pedir un análisis o un pull request |
Los permisos no se incluyen unos a otros. Un token para un agente de código necesita read. Un token para tu CI, para subir source maps, necesita admin. Cada endpoint de esta referencia dice qué permiso necesita.
Crea tokens con POST /v1/tokens, con sypnia token create, o en la app en Sypnia Cloud. El secreto de un token se muestra una sola vez.
El parámetro project
Un token de API pertenece a un proyecto, así que nunca dices de qué proyecto hablas. El token raíz ve todos los proyectos, así que con él debes agregar project (el id o el slug) a cada llamada que trabaja sobre un proyecto:
curl "https://sypnia.example.com/v1/problems?project=shop" \
-H "Authorization: Bearer $SYPNIA_ROOT_TOKEN"Qué tiene el motor, y qué tiene solo Sypnia Cloud
| Motor de SypniaCódigo abierto, en tu propia infraestructura | Sypnia CloudServicio pago, con un plan gratis | |
|---|---|---|
| Proyectos, llaves de ingesta, tokens de API | Sí, por esta API | Sí. Los proyectos se crean en la app |
| Usuarios, organizaciones, roles, planes, facturación | No existen | En la app. Sin API pública al lanzar |
| Pull requests | No están en el motor: 404 cloud_only | POST /v1/problems/{problem}/pull-request |
| Límites | Ninguno puesto por nosotros. Cuotas opcionales en tu configuración | Los de tu plan. Mira GET /v1/usage |
Convenciones
Son las mismas en todos los endpoints y se explican una sola vez, en Errores, límites, paginación:
- Los errores tienen una sola forma:
{ "error": { "code", "message", "doc_url", "request_id" } }. - Las listas devuelven
{ "data": [...], "next_cursor": … }. Devuelvenext_cursorcomocursor. - Los rangos de tiempo usan
sinceyuntil: una fecha, o un valor relativo como24ho7d. - El entorno: los endpoints de lectura reciben
environment, por defectoproduction. - Las fechas son ISO 8601 en UTC. Las duraciones van en milisegundos y terminan en
_ms. - La frescura: un problema nuevo aparece a menos de 2 minutos de su primer evento; los conteos, los números de rendimiento y la lista de sesiones están completos en menos de 10 minutos.
- Los nombres de endpoints, parámetros, campos y valores están en inglés y no se traducen.
Los tres endpoints que cubren un proyecto
Comprobar una credencial
/v1/whoami MotorNube Dice qué es la credencial de la petición y qué puede hacer. Sirve para probar un token nuevo, y en scripts antes de un trabajo largo. Funciona con cualquier credencial, incluida una llave de ingesta.
Petición
curl https://api.sypnia.com/v1/whoami \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Respuesta200
{
"credential": "api_token",
"id": "tok_9r4t6y2u8i1o",
"name": "Cursor",
"scopes": [
"read",
"replay"
],
"project": {
"id": "prj_5k2m9x4q7w1z",
"slug": "shop",
"name": "Shop"
},
"deployment": "cloud",
"engine_version": "1.0.0"
}Qué está fallando ahora
/v1/summary MotorNube Una sola respuesta a «¿qué está fallando en producción?»: los problemas abiertos que más importan, las comprobaciones de disponibilidad caídas, las páginas que se pusieron lentas y qué tan frescos están los datos. Es lo que devuelve la herramienta MCP health, y con esto se arma el resumen diario de Sypnia Cloud.
state es failing cuando una comprobación está caída o un problema se abrió o volvió en el periodo, degraded cuando solo hay problemas viejos abiertos o una página se puso lenta, y ok en los demás casos.
Parámetros de consulta
-
projectstring opcionalEl id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es
403. -
environmentstring opcionalEl entorno que se lee. Cualquier nombre que el proyecto haya enviado, o
all.Por defecto:
production -
sincestring opcionalInicio del periodo que cuenta como «ahora». Una fecha ISO 8601 o un valor relativo, de
1ha7d.Por defecto:
24h
Petición
curl "https://api.sypnia.com/v1/summary" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Respuesta200
{
"project": {
"id": "prj_5k2m9x4q7w1z",
"slug": "shop",
"name": "Shop"
},
"environment": "production",
"generated_at": "2026-03-12T10:35:00Z",
"data_through": "2026-03-12T10:34:10Z",
"state": "failing",
"sentence": "1 new problem in the last 24 hours. Every uptime check is up. 1 page got slower.",
"problems": {
"open": 1,
"new": 1,
"regressed": 0,
"top": [
{
"id": "prb_8f3k2m9x4q7w",
"slug": "pay-button-does-nothing",
"sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
"title": "createPayment answered 400 in POST /api/checkout",
"confidence": "high",
"people": 3,
"sessions": 3,
"first_seen": "2026-03-12T09:12:04Z",
"last_seen": "2026-03-12T10:31:47Z",
"first_release": "4f2a91c",
"regressed": false
}
]
},
"uptime": {
"checks": 1,
"down": []
},
"performance": {
"slower_pages": [
{
"route": "/search",
"lcp_p75_ms": 3100,
"previous_lcp_p75_ms": 1900,
"views": 1840
}
],
"failing_api": []
},
"traffic": {
"sessions": 498,
"people": 412,
"errors": 5
},
"alerts": {
"unacknowledged": 1
}
}Buscar en un proyecto
/v1/search MotorNube Encuentra problemas, sesiones, personas, cuentas, trazas, versiones y páginas con un solo texto. No distingue mayúsculas ni tildes.
| Lo que escribes | Lo que encuentra |
|---|---|
Palabras (pay button, amount_required) | Problemas por su frase, título, slug, archivo o función. Páginas por su ruta |
| El id de una sesión o de una traza, completo o sus primeros 8 caracteres o más | Esa sesión o traza |
| El id, el nombre o el correo de una persona; el id o el nombre de una cuenta | La persona o la cuenta, con sus últimas sesiones |
El nombre de una versión o su comienzo (4f2a) | La versión |
Los nombres y correos solo se pueden buscar si tu app los envió con identify().
Parámetros de consulta
-
projectstring opcionalEl id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es
403. -
environmentstring opcionalEl entorno que se lee. Cualquier nombre que el proyecto haya enviado, o
all.Por defecto:
production -
qstring, hasta 120 caracteres obligatorioEl texto que se busca. De 2 a 120 caracteres.
-
typesstring opcionalLista separada por comas de dónde buscar.
Por defecto:
problems,sessions,people,accounts,traces,releases,pages -
sincestring opcionalSolo cuentan las sesiones, trazas y actividad posteriores a este momento.
Por defecto:
30d -
limitinteger, 1 a 25 opcionalMáximo de resultados por tipo.
Por defecto:
10
Petición
curl "https://api.sypnia.com/v1/search?q=pay+button" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Respuesta200
{
"q": "pay button",
"problems": [
{
"id": "prb_8f3k2m9x4q7w",
"slug": "pay-button-does-nothing",
"status": "open",
"sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
"title": "createPayment answered 400 in POST /api/checkout",
"people": 3,
"last_seen": "2026-03-12T10:31:47Z"
}
],
"sessions": [],
"people": [],
"accounts": [],
"traces": [],
"releases": [],
"pages": []
}Errores
- 400
invalid_requestFalta
q, tiene menos de 2 caracteres o más de 120.
Los errores que cualquier endpoint puede responder (401, 403, 429, 500, 503) están en Errores, límites, paginación.