Docs

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.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. URL base
  2. Autenticación
  3. Permisos de un token de API
  4. El parámetro project
  5. Qué tiene el motor, y qué tiene solo Sypnia Cloud
  6. Convenciones
  7. Los tres endpoints que cubren un proyecto
  8. Comprobar una credencial
  9. Qué está fallando ahora
  10. Buscar en 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óndeLeer y administrarEnviar datos (ingesta, OTLP)
Sypnia Cloudhttps://api.sypnia.com/v1https://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:

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

CredencialCómo se ve¿Secreta?Qué puede hacerDónde existe
Llave de ingestaspk_ y 32 caracteres hexadecimalesNo. Va dentro de tu appEnviar datos, y nada más. Solo la aceptan los endpoints de ingesta y de OTLPMotor y nube
Token de APIsps_ y 40 caracteresSíLeer y administrar un proyecto, dentro de sus permisosMotor y nube
Token raízCualquier cadena de 32 caracteres o más que tú elijasSíTodo, en todos los proyectos del motorSolo en el motor. Se define con SYPNIA_ROOT_TOKEN

Permisos de un token de API

PermisoQué permite
readLeer 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
replayTraer grabaciones y capturas de página. Muestran la página como la vio la persona, por eso este permiso va aparte
adminTodo 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:

Terminal
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

El motor de Sypnia y Sypnia Cloud, comparados
Motor de SypniaCódigo abierto, en tu propia infraestructuraSypnia CloudServicio pago, con un plan gratis
Proyectos, llaves de ingesta, tokens de APISí, por esta APISí. Los proyectos se crean en la app
Usuarios, organizaciones, roles, planes, facturaciónNo existenEn la app. Sin API pública al lanzar
Pull requestsNo están en el motor: 404 cloud_onlyPOST /v1/problems/{problem}/pull-request
LímitesNinguno puesto por nosotros. Cuotas opcionales en tu configuraciónLos 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": … }. Devuelve next_cursor como cursor.
  • Los rangos de tiempo usan since y until: una fecha, o un valor relativo como 24h o 7d.
  • El entorno: los endpoints de lectura reciben environment, por defecto production.
  • 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

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

Autenticación
Cualquier credencial

Petición

Terminal
curl https://api.sypnia.com/v1/whoami \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

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

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

Autenticación
Token de API (read)

Parámetros de consulta

  • project
    string opcional

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

  • environment
    string opcional

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • since
    string opcional

    Inicio del periodo que cuenta como «ahora». Una fecha ISO 8601 o un valor relativo, de 1h a 7d.

    Por defecto: 24h

Petición

Terminal
curl "https://api.sypnia.com/v1/summary" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

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

GET /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 escribesLo 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ásEsa sesión o traza
El id, el nombre o el correo de una persona; el id o el nombre de una cuentaLa 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().

Autenticación
Token de API (read)

Parámetros de consulta

  • project
    string opcional

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

  • environment
    string opcional

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • q
    string, hasta 120 caracteres obligatorio

    El texto que se busca. De 2 a 120 caracteres.

  • types
    string opcional

    Lista separada por comas de dónde buscar.

    Por defecto: problems,sessions,people,accounts,traces,releases,pages

  • since
    string opcional

    Solo cuentan las sesiones, trazas y actividad posteriores a este momento.

    Por defecto: 30d

  • limit
    integer, 1 a 25 opcional

    Máximo de resultados por tipo.

    Por defecto: 10

Petición

Terminal
curl "https://api.sypnia.com/v1/search?q=pay+button" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

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

  • 400invalid_request

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

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