Docs

Proyectos, llaves y tokens

Crea proyectos, llaves de ingesta y tokens de API en un motor alojado por ti, administra llaves y tokens en cualquier parte, y lee el uso.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. El objeto proyecto
  2. El objeto llave de ingesta
  3. El objeto token de API
  4. Listar proyectos
  5. Crear un proyecto
  6. Traer un proyecto
  7. Actualizar un proyecto
  8. Borrar un proyecto
  9. Listar llaves de ingesta
  10. Crear una llave de ingesta
  11. Revocar una llave de ingesta
  12. Listar tokens de API
  13. Crear un token de API
  14. Revocar un token de API
  15. Traer el uso y los límites

El motor sabe tres cosas sobre el acceso: proyectos, llaves de ingesta y tokens de API. No tiene usuarios ni organizaciones. Esos existen solo en Sypnia Cloud, en la app, y no tienen API pública al lanzar.

QuieresMotor (alojamiento propio)Sypnia Cloud
Crear o borrar un proyectoEsta API, con el token raízEn la app
Crear o revocar llaves de ingesta y tokens de APIEsta API, con el token raíz o un token admin del proyectoEsta API con un token admin, o en la app
Invitar personas, cambiar de plan, ver facturasNo existeEn la app

El objeto proyecto

Campos

  • id
    string opcional

    prj_….

  • slug
    string opcional

    Un nombre corto para URLs y comandos. Letras minúsculas, dígitos y guiones, de 2 a 40 caracteres. No se puede cambiar.

  • name
    string opcional

    El nombre que ve la gente.

  • timezone
    string opcional

    Una zona horaria IANA. Los días, «hoy» y «ayer» se cortan en ella.

  • environments
    lista de string opcional

    Los entornos que enviaron datos en los últimos 30 días.

  • settings
    object opcional
  • settings.allowed_origins
    lista de string, hasta 50 elementos

    Orígenes que pueden enviar datos desde un navegador, como https://shop.example.com. Un *. al comienzo acepta subdominios. Vacío acepta cualquier origen.

  • settings.replay
    object

    Reglas de grabación. El SDK las lee de la llamada de configuración de la ingesta.

  • settings.replay.enabled
    boolean

    false apaga la grabación en el proyecto.

    Por defecto: true

  • settings.replay.sample_rate
    number, 0 a 1

    La parte de las sesiones que se graba desde su primer momento. Las demás igual se graban desde 30 segundos antes de su primer error, clic de rabia o clic muerto.

    Por defecto: 0.1

  • settings.replay.mask_all_text
    boolean

    true enmascara todo el texto de la página, no solo lo que la gente escribe. Lo que la gente escribe siempre se enmascara, y los campos de contraseña, de tarjeta y de código de un solo uso nunca se pueden mostrar.

    Por defecto: false

  • settings.replay.blocked_routes
    lista de string, hasta 100 elementos

    Rutas donde no se graba nada ni se toma ninguna captura. * vale por cualquier texto: /account/*.

  • settings.replay.always_record
    lista de object, hasta 100 elementos

    Personas y cuentas cuyas sesiones se graban siempre desde el comienzo, por ejemplo mientras ayudas a un cliente.

  • settings.snapshots
    object
  • settings.snapshots.sample_rate
    number, 0 a 1

    La parte de las sesiones que toma capturas de página, para los mapas de clics.

    Por defecto: 0.5

  • settings.agent
    object
  • settings.agent.enabled
    boolean

    false apaga el agente en este proyecto: sin análisis y sin sugerencias semanales hechas por un modelo. No se envía nada a un proveedor de IA.

    Por defecto: true

  • settings.agent.language
    string

    El idioma en el que escribe el agente, como etiqueta BCP 47 (en, es).

    Por defecto: en

  • settings.agent.auto_pull_requests
    string

    Solo en Sypnia Cloud. high_confidence abre un pull request por su cuenta cuando un análisis es high. Uno de: off, high_confidence.

    Por defecto: off

  • created_at
    timestamp opcional

El objeto llave de ingesta

Campos

  • id
    string opcional

    El id del registro, key_…. Úsalo para revocar la llave.

  • key
    string opcional

    La llave misma, spk_ y 32 caracteres hexadecimales. Es pública: va en el código de tu app.

  • name
    string opcional
  • rate_limit_per_minute
    integer opcional

    Peticiones por minuto que se aceptan desde una misma dirección con esta llave.

  • created_at
    timestamp opcional
  • last_used_at
    timestamp o null opcional

    Con precisión de una hora.

  • revoked_at
    timestamp o null opcional

El objeto token de API

Campos

  • id
    string opcional

    El id del registro, tok_…. Úsalo para revocar el token.

  • name
    string opcional
  • prefix
    string opcional

    Los primeros 12 caracteres del secreto.

  • scopes
    lista de string opcional

    Uno de: read, replay, admin.

  • created_at
    timestamp opcional
  • last_used_at
    timestamp o null opcional

    Con precisión de una hora.

  • expires_at
    timestamp o null opcional
  • revoked_at
    timestamp o null opcional

Listar proyectos

GET /v1/projects MotorNube

Con el token raíz, todos los proyectos del motor. Con un token de API, una lista con el único proyecto al que pertenece el token.

Autenticación
Token raíz, o token de API (read)

Parámetros de consulta

  • limit
    integer, 1 a 200 opcional

    Máximo de elementos que se devuelven.

    Por defecto: 50

  • cursor
    string opcional

    El next_cursor de la página anterior. Deja iguales todos los demás parámetros.

Petición

Terminal
curl "https://sypnia.example.com/v1/projects" \
  -H "Authorization: Bearer $SYPNIA_ROOT_TOKEN"

Respuesta200

JSON
{
  "data": [
    {
      "id": "prj_5k2m9x4q7w1z",
      "slug": "shop",
      "name": "Shop",
      "timezone": "UTC",
      "environments": [
        "production",
        "development"
      ],
      "settings": {
        "allowed_origins": [
          "https://shop.example.com"
        ],
        "replay": {
          "enabled": true,
          "sample_rate": 0.1,
          "mask_all_text": false,
          "blocked_routes": [
            "/account/cards"
          ],
          "always_record": [
            {
              "person": "u_1042",
              "note": "Reported the checkout bug",
              "until": "2026-03-26T00:00:00Z"
            }
          ]
        },
        "snapshots": {
          "sample_rate": 0.5
        },
        "agent": {
          "enabled": true,
          "language": "en",
          "auto_pull_requests": "off"
        }
      },
      "created_at": "2026-02-02T09:15:00Z"
    }
  ],
  "next_cursor": null
}

Crear un proyecto

POST /v1/projects Motor

Crea un proyecto y su primera llave de ingesta, que vuelve en ingest_key. Solo en motores alojados por ti: en Sypnia Cloud los proyectos se crean en la app, donde pertenecen a una organización y a un plan, y esta llamada responde 403 cloud_managed.

Autenticación
Token raíz

Encabezados

  • Idempotency-Key
    string, hasta 255 caracteres opcional

    Un valor tuyo, de 1 a 255 caracteres, que hace que la llamada se pueda repetir sin riesgo. Mira idempotencia.

Cuerpo

  • name
    string, hasta 80 caracteres obligatorio

    El nombre que ve la gente.

  • slug
    string opcional

    Por defecto, el nombre en minúsculas con guiones.

  • timezone
    string opcional

    Una zona horaria IANA, como America/Bogota.

    Por defecto: UTC

  • settings
    object opcional
  • settings.allowed_origins
    lista de string, hasta 50 elementos

    Orígenes que pueden enviar datos desde un navegador, como https://shop.example.com. Un *. al comienzo acepta subdominios. Vacío acepta cualquier origen.

  • settings.replay
    object

    Reglas de grabación. El SDK las lee de la llamada de configuración de la ingesta.

  • settings.replay.enabled
    boolean

    false apaga la grabación en el proyecto.

    Por defecto: true

  • settings.replay.sample_rate
    number, 0 a 1

    La parte de las sesiones que se graba desde su primer momento. Las demás igual se graban desde 30 segundos antes de su primer error, clic de rabia o clic muerto.

    Por defecto: 0.1

  • settings.replay.mask_all_text
    boolean

    true enmascara todo el texto de la página, no solo lo que la gente escribe. Lo que la gente escribe siempre se enmascara, y los campos de contraseña, de tarjeta y de código de un solo uso nunca se pueden mostrar.

    Por defecto: false

  • settings.replay.blocked_routes
    lista de string, hasta 100 elementos

    Rutas donde no se graba nada ni se toma ninguna captura. * vale por cualquier texto: /account/*.

  • settings.replay.always_record
    lista de object, hasta 100 elementos

    Personas y cuentas cuyas sesiones se graban siempre desde el comienzo, por ejemplo mientras ayudas a un cliente.

  • settings.snapshots
    object
  • settings.snapshots.sample_rate
    number, 0 a 1

    La parte de las sesiones que toma capturas de página, para los mapas de clics.

    Por defecto: 0.5

  • settings.agent
    object
  • settings.agent.enabled
    boolean

    false apaga el agente en este proyecto: sin análisis y sin sugerencias semanales hechas por un modelo. No se envía nada a un proveedor de IA.

    Por defecto: true

  • settings.agent.language
    string

    El idioma en el que escribe el agente, como etiqueta BCP 47 (en, es).

    Por defecto: en

  • settings.agent.auto_pull_requests
    string

    Solo en Sypnia Cloud. high_confidence abre un pull request por su cuenta cuando un análisis es high. Uno de: off, high_confidence.

    Por defecto: off

Petición

Terminal
curl -X POST "https://sypnia.example.com/v1/projects" \
  -H "Authorization: Bearer $SYPNIA_ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop", "slug": "shop", "timezone": "UTC"}'

Respuesta201

JSON
{
  "id": "prj_5k2m9x4q7w1z",
  "slug": "shop",
  "name": "Shop",
  "timezone": "UTC",
  "environments": [],
  "settings": {
    "allowed_origins": [],
    "replay": {
      "enabled": true,
      "sample_rate": 0.1,
      "mask_all_text": false,
      "blocked_routes": [],
      "always_record": []
    },
    "snapshots": {
      "sample_rate": 0.5
    },
    "agent": {
      "enabled": true,
      "language": "en",
      "auto_pull_requests": "off"
    }
  },
  "created_at": "2026-02-02T09:15:00Z",
  "ingest_key": {
    "id": "key_3n8v2c6b1m4x",
    "key": "spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e",
    "name": "Default",
    "rate_limit_per_minute": 600,
    "created_at": "2026-02-02T09:15:00Z",
    "last_used_at": null,
    "revoked_at": null
  }
}

Errores

  • 400invalid_request

    Falta name, slug tiene caracteres distintos de a-z 0-9 -, o timezone no es un nombre IANA.

  • 403cloud_managed

    La petición llegó a Sypnia Cloud. Crea los proyectos en la app.

  • 403forbidden

    La credencial no es el token raíz.

  • 409conflict

    Ya existe un proyecto con este slug.

Traer un proyecto

GET /v1/projects/{project_ref} MotorNube

Un proyecto con sus ajustes.

Autenticación
Token raíz, o token de API (read) de ese proyecto

Parámetros de ruta

  • project_ref
    string obligatorio

    El id del proyecto (prj_…) o su slug.

Petición

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

Respuesta200

JSON
{
  "id": "prj_5k2m9x4q7w1z",
  "slug": "shop",
  "name": "Shop",
  "timezone": "UTC",
  "environments": [
    "production",
    "development"
  ],
  "settings": {
    "allowed_origins": [
      "https://shop.example.com"
    ],
    "replay": {
      "enabled": true,
      "sample_rate": 0.1,
      "mask_all_text": false,
      "blocked_routes": [
        "/account/cards"
      ],
      "always_record": [
        {
          "person": "u_1042",
          "note": "Reported the checkout bug",
          "until": "2026-03-26T00:00:00Z"
        }
      ]
    },
    "snapshots": {
      "sample_rate": 0.5
    },
    "agent": {
      "enabled": true,
      "language": "en",
      "auto_pull_requests": "off"
    }
  },
  "created_at": "2026-02-02T09:15:00Z"
}

Errores

  • 404not_found

    No existe ese proyecto, o el token es de otro.

Actualizar un proyecto

PATCH /v1/projects/{project_ref} MotorNube

Cambia los campos que envías y deja los demás. settings se mezcla clave por clave: envía solo los ajustes que quieres cambiar. Las reglas de grabación (settings.replay, settings.snapshots) llegan a los navegadores con su siguiente sesión, por la llamada de configuración de la ingesta; no hace falta desplegar.

Autenticación
Token raíz, o token de API (admin) de ese proyecto

Parámetros de ruta

  • project_ref
    string obligatorio

    El id del proyecto (prj_…) o su slug.

Cuerpo

  • name
    string, hasta 80 caracteres opcional

    El nombre que ve la gente.

  • timezone
    string opcional

    Una zona horaria IANA. Los días pasados no se vuelven a cortar.

  • settings
    object opcional
  • settings.allowed_origins
    lista de string, hasta 50 elementos

    Orígenes que pueden enviar datos desde un navegador, como https://shop.example.com. Un *. al comienzo acepta subdominios. Vacío acepta cualquier origen.

  • settings.replay
    object

    Reglas de grabación. El SDK las lee de la llamada de configuración de la ingesta.

  • settings.replay.enabled
    boolean

    false apaga la grabación en el proyecto.

    Por defecto: true

  • settings.replay.sample_rate
    number, 0 a 1

    La parte de las sesiones que se graba desde su primer momento. Las demás igual se graban desde 30 segundos antes de su primer error, clic de rabia o clic muerto.

    Por defecto: 0.1

  • settings.replay.mask_all_text
    boolean

    true enmascara todo el texto de la página, no solo lo que la gente escribe. Lo que la gente escribe siempre se enmascara, y los campos de contraseña, de tarjeta y de código de un solo uso nunca se pueden mostrar.

    Por defecto: false

  • settings.replay.blocked_routes
    lista de string, hasta 100 elementos

    Rutas donde no se graba nada ni se toma ninguna captura. * vale por cualquier texto: /account/*.

  • settings.replay.always_record
    lista de object, hasta 100 elementos

    Personas y cuentas cuyas sesiones se graban siempre desde el comienzo, por ejemplo mientras ayudas a un cliente.

  • settings.snapshots
    object
  • settings.snapshots.sample_rate
    number, 0 a 1

    La parte de las sesiones que toma capturas de página, para los mapas de clics.

    Por defecto: 0.5

  • settings.agent
    object
  • settings.agent.enabled
    boolean

    false apaga el agente en este proyecto: sin análisis y sin sugerencias semanales hechas por un modelo. No se envía nada a un proveedor de IA.

    Por defecto: true

  • settings.agent.language
    string

    El idioma en el que escribe el agente, como etiqueta BCP 47 (en, es).

    Por defecto: en

  • settings.agent.auto_pull_requests
    string

    Solo en Sypnia Cloud. high_confidence abre un pull request por su cuenta cuando un análisis es high. Uno de: off, high_confidence.

    Por defecto: off

Petición

Terminal
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"replay": {"blocked_routes": ["/account/cards"]}}}'

Respuesta200

JSON
{
  "id": "prj_5k2m9x4q7w1z",
  "slug": "shop",
  "name": "Shop",
  "timezone": "UTC",
  "environments": [
    "production",
    "development"
  ],
  "settings": {
    "allowed_origins": [
      "https://shop.example.com"
    ],
    "replay": {
      "enabled": true,
      "sample_rate": 0.1,
      "mask_all_text": false,
      "blocked_routes": [
        "/account/cards"
      ],
      "always_record": [
        {
          "person": "u_1042",
          "note": "Reported the checkout bug",
          "until": "2026-03-26T00:00:00Z"
        }
      ]
    },
    "snapshots": {
      "sample_rate": 0.5
    },
    "agent": {
      "enabled": true,
      "language": "en",
      "auto_pull_requests": "off"
    }
  },
  "created_at": "2026-02-02T09:15:00Z"
}

Errores

  • 400invalid_request

    Un ajuste está fuera de rango o no existe. param lo nombra, por ejemplo settings.replay.sample_rate.

  • 404not_found

    No existe ese proyecto, o el token es de otro.

Borrar un proyecto

DELETE /v1/projects/{project_ref} Motor

Borra para siempre el proyecto, sus llaves y tokens, y todos sus datos. La ingesta con sus llaves se detiene de inmediato; los objetos guardados se quitan en menos de 24 horas. Solo en motores alojados por ti. Para confirmar, envía el slug del proyecto en el parámetro confirm.

Autenticación
Token raíz

Parámetros de ruta

  • project_ref
    string obligatorio

    El id del proyecto (prj_…) o su slug.

Parámetros de consulta

  • confirm
    string obligatorio

    El slug del proyecto, escrito otra vez.

Petición

Terminal
curl -X DELETE "https://sypnia.example.com/v1/projects/shop?confirm=shop" \
  -H "Authorization: Bearer $SYPNIA_ROOT_TOKEN"

Errores

  • 400invalid_request

    Falta confirm o no es el slug del proyecto.

  • 403cloud_managed

    La petición llegó a Sypnia Cloud. Borra los proyectos en la app.

  • 404not_found

    No existe ese proyecto.

Listar llaves de ingesta

GET /v1/keys MotorNube

Las llaves de ingesta del proyecto, incluidas las revocadas. Una llave de ingesta es pública, así que la lista muestra cada llave completa.

Autenticación
Token raíz, o token de API (admin)

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.

Petición

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

Respuesta200

JSON
{
  "data": [
    {
      "id": "key_3n8v2c6b1m4x",
      "key": "spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e",
      "name": "Web app",
      "rate_limit_per_minute": 600,
      "created_at": "2026-02-02T09:15:00Z",
      "last_used_at": "2026-03-12T10:31:58Z",
      "revoked_at": null
    }
  ],
  "next_cursor": null
}

Crear una llave de ingesta

POST /v1/keys MotorNube

Crea otra llave de ingesta para el proyecto. Dale a cada app o plataforma su propia llave (web, móvil, servidor), para poder revocar una sin detener las demás. Un proyecto tiene como máximo 20 llaves sin revocar.

Autenticación
Token raíz, o token de API (admin)

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.

Encabezados

  • Idempotency-Key
    string, hasta 255 caracteres opcional

    Un valor tuyo, de 1 a 255 caracteres, que hace que la llamada se pueda repetir sin riesgo. Mira idempotencia.

Cuerpo

  • name
    string, hasta 80 caracteres obligatorio

    Para qué es la llave.

  • rate_limit_per_minute
    integer, 10 a 6,000 opcional

    Peticiones por minuto que se aceptan desde una misma dirección con esta llave. Súbelo para un servidor que envía por muchas personas desde una sola dirección.

    Por defecto: 600

Petición

Terminal
curl -X POST "https://api.sypnia.com/v1/keys" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Checkout API"}'

Respuesta201

JSON
{
  "id": "key_8b5n2m7v4c1x",
  "key": "spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82",
  "name": "Checkout API",
  "rate_limit_per_minute": 600,
  "created_at": "2026-03-12T10:40:00Z",
  "last_used_at": null,
  "revoked_at": null
}

Errores

  • 409limit_reached

    El proyecto ya tiene 20 llaves sin revocar.

Revocar una llave de ingesta

DELETE /v1/keys/{key_id} MotorNube

Revoca la llave. La ingesta con ella responde 401 en menos de un minuto. El registro se queda en la lista con revoked_at. Revocar no se puede deshacer; crea una llave nueva.

Autenticación
Token raíz, o token de API (admin)

Parámetros de ruta

  • key_id
    string obligatorio

    El id del registro de la llave (key_…), no la llave misma.

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.

Petición

Terminal
curl -X DELETE "https://api.sypnia.com/v1/keys/key_8b5n2m7v4c1x" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"

Errores

  • 404not_found

    Ninguna llave del proyecto tiene este id.

  • 409conflict

    Es la última llave sin revocar del proyecto. Crea otra primero, para que tu app nunca se quede sin una.

Listar tokens de API

GET /v1/tokens MotorNube

Los tokens de API del proyecto, incluidos los revocados y los vencidos. El secreto nunca se vuelve a mostrar; prefix son sus primeros 12 caracteres, suficientes para reconocerlo.

Autenticación
Token raíz, o token de API (admin)

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.

Petición

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

Respuesta200

JSON
{
  "data": [
    {
      "id": "tok_9r4t6y2u8i1o",
      "name": "Cursor",
      "prefix": "sps_4Kq9Zt2M",
      "scopes": [
        "read",
        "replay"
      ],
      "created_at": "2026-02-02T09:18:00Z",
      "last_used_at": "2026-03-12T10:34:10Z",
      "expires_at": null,
      "revoked_at": null
    }
  ],
  "next_cursor": null
}

Crear un token de API

POST /v1/tokens MotorNube

Crea un token de API para el proyecto. El secreto está en token y se muestra solo en esta respuesta: el motor guarda un hash. Dale a un token los mínimos permisos que alcancen para el trabajo:

PermisoQué permite
readLeer todo salvo el contenido de las grabaciones. Sus únicas escrituras son marcas reversibles: 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
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

Los permisos no se incluyen unos a otros: un token que deba leer y administrar necesita read y admin.

Autenticación
Token raíz, o token de API (admin)

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.

Encabezados

  • Idempotency-Key
    string, hasta 255 caracteres opcional

    Un valor tuyo, de 1 a 255 caracteres, que hace que la llamada se pueda repetir sin riesgo. Mira idempotencia.

Cuerpo

  • name
    string, hasta 80 caracteres obligatorio

    Quién o qué lo va a usar. Aparece en resolved_by y en el registro de cambios.

  • scopes
    lista de string obligatorio

    Qué puede hacer el token. Uno de: read, replay, admin.

  • expires_at
    timestamp opcional

    Cuándo deja de funcionar el token. Omítelo para un token que no vence.

Petición

Terminal
curl -X POST "https://api.sypnia.com/v1/tokens" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Cursor", "scopes": ["read", "replay"]}'

Respuesta201

JSON
{
  "id": "tok_9r4t6y2u8i1o",
  "name": "Cursor",
  "prefix": "sps_4Kq9Zt2M",
  "token": "sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iO",
  "scopes": [
    "read",
    "replay"
  ],
  "created_at": "2026-02-02T09:18:00Z",
  "last_used_at": null,
  "expires_at": null,
  "revoked_at": null
}

Errores

  • 400invalid_request

    scopes está vacío o tiene un valor distinto de read, replay, admin; o expires_at está en el pasado.

  • 409limit_reached

    El proyecto ya tiene 50 tokens sin revocar.

Revocar un token de API

DELETE /v1/tokens/{token_id} MotorNube

Revoca el token. Las peticiones con él responden 401 en menos de un minuto. Un token se puede revocar a sí mismo.

Autenticación
Token raíz, o token de API (admin)

Parámetros de ruta

  • token_id
    string obligatorio

    El id del registro del token (tok_…), no el secreto.

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.

Petición

Terminal
curl -X DELETE "https://api.sypnia.com/v1/tokens/tok_9r4t6y2u8i1o" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"

Errores

  • 404not_found

    Ningún token del proyecto tiene este id.

Traer el uso y los límites

GET /v1/usage MotorNube

Lo que el proyecto usó en el periodo actual y cuáles son sus límites. Un límite null significa sin límite: así son todos en un motor alojado por ti, salvo que definas una cuota en su configuración. En Sypnia Cloud los límites son los del plan y el periodo es el mes calendario, en UTC. Los límites de un plan son de la organización y los comparten sus proyectos: used es la parte de este proyecto, organization_used es lo que usaron todos sus proyectos juntos, y el límite se alcanza cuando organization_used llega a limit.

Los contadores son exactos y se actualizan a medida que llegan los datos. dropped_over_limit es cuántos eventos o grabaciones se rechazaron por haber llegado a un límite: Sypnia nunca descarta en silencio, lo cuenta aquí y le dice al SDK que baje el ritmo.

ContadorQué cuenta como uno
eventsUn error, una traza (una petición con sus spans) o una muestra de rendimiento (una vista de página con sus métricas). Los clics, los eventos propios y los trozos de grabación no cuentan
replaysUna sesión que tiene grabación
analysesUna corrida del agente sobre un problema. Se cuenta por día
pull_requestsUn pull request abierto por Sypnia. Solo en Sypnia Cloud
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.

  • period
    string opcional

    Un mes como YYYY-MM, para leer un periodo pasado. Hasta 12 meses atrás.

Petición

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

Respuesta200

JSON
{
  "project": {
    "id": "prj_5k2m9x4q7w1z",
    "slug": "shop",
    "name": "Shop"
  },
  "plan": "builder",
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-04-01T00:00:00Z"
  },
  "events": {
    "used": 18240,
    "organization_used": 21902,
    "limit": 50000,
    "dropped_over_limit": 0
  },
  "replays": {
    "used": 212,
    "organization_used": 240,
    "limit": 500,
    "dropped_over_limit": 0
  },
  "analyses": {
    "used_today": 4,
    "limit_per_day": 100,
    "used_this_period": 37
  },
  "pull_requests": {
    "used": 6,
    "organization_used": 6,
    "limit": 50,
    "dropped_over_limit": 0
  },
  "uptime_checks": {
    "used": 1,
    "limit": 5
  },
  "retention_days": {
    "events": 30,
    "replays": 30
  },
  "slow_down": null,
  "daily": [
    {
      "day": "2026-03-11",
      "events": 1610,
      "replays": 19,
      "analyses": 2
    },
    {
      "day": "2026-03-12",
      "events": 702,
      "replays": 9,
      "analyses": 4
    }
  ]
}

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