# 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: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/api/projects-keys-and-tokens/

Para agentes: Referencia de los endpoints de proyectos, llaves de ingesta, tokens de API y uso de la API de Sypnia, con lo que existe solo en el motor y lo que se maneja en la app de Sypnia Cloud.

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.

| Quieres                                           | Motor (alojamiento propio)                                  | Sypnia Cloud                               |
| ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------ |
| Crear o borrar un proyecto                        | Esta API, con el token raíz                                 | En la app                                  |
| Crear o revocar llaves de ingesta y tokens de API | Esta API, con el token raíz o un token `admin` del proyecto | Esta API con un token `admin`, o en la app |
| Invitar personas, cambiar de plan, ver facturas   | No existe                                                   | En 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, por defecto `true`): `false` apaga la grabación en el proyecto.
- `settings.replay.sample_rate` (number, 0 a 1, por defecto `0.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.
- `settings.replay.mask_all_text` (boolean, por defecto `false`): `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.
- `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, por defecto `0.5`): La parte de las sesiones que toma capturas de página, para los mapas de clics.
- `settings.agent` (object)
- `settings.agent.enabled` (boolean, por defecto `true`): `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.
- `settings.agent.language` (string, por defecto `en`): El idioma en el que escribe el agente, como etiqueta BCP 47 (`en`, `es`).
- `settings.agent.auto_pull_requests` (string, por defecto `off`): Solo en Sypnia Cloud. `high_confidence` abre un pull request por su cuenta cuando un análisis es `high`. Uno de: `off`, `high_confidence`.
- `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` \[Motor, Nube]

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, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

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

**Respuesta (200):**

```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](https://docs.sypnia.com/es/api/errors-limits-pagination#idempotency).

**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, por defecto `UTC`): Una zona horaria IANA, como `America/Bogota`.
- `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, por defecto `true`): `false` apaga la grabación en el proyecto.
- `settings.replay.sample_rate` (number, 0 a 1, por defecto `0.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.
- `settings.replay.mask_all_text` (boolean, por defecto `false`): `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.
- `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, por defecto `0.5`): La parte de las sesiones que toma capturas de página, para los mapas de clics.
- `settings.agent` (object)
- `settings.agent.enabled` (boolean, por defecto `true`): `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.
- `settings.agent.language` (string, por defecto `en`): El idioma en el que escribe el agente, como etiqueta BCP 47 (`en`, `es`).
- `settings.agent.auto_pull_requests` (string, por defecto `off`): Solo en Sypnia Cloud. `high_confidence` abre un pull request por su cuenta cuando un análisis es `high`. Uno de: `off`, `high_confidence`.

**Petición:**

```bash
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"}'
```

**Respuesta (201):**

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

- `400` `invalid_request`: Falta `name`, `slug` tiene caracteres distintos de `a-z 0-9 -`, o `timezone` no es un nombre IANA.
- `403` `cloud_managed`: La petición llegó a Sypnia Cloud. Crea los proyectos en la app.
- `403` `forbidden`: La credencial no es el token raíz.
- `409` `conflict`: Ya existe un proyecto con este `slug`.

## Traer un proyecto

`GET /v1/projects/{project_ref}` \[Motor, Nube]

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

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

**Respuesta (200):**

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

- `404` `not_found`: No existe ese proyecto, o el token es de otro.

## Actualizar un proyecto

`PATCH /v1/projects/{project_ref}` \[Motor, Nube]

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, por defecto `true`): `false` apaga la grabación en el proyecto.
- `settings.replay.sample_rate` (number, 0 a 1, por defecto `0.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.
- `settings.replay.mask_all_text` (boolean, por defecto `false`): `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.
- `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, por defecto `0.5`): La parte de las sesiones que toma capturas de página, para los mapas de clics.
- `settings.agent` (object)
- `settings.agent.enabled` (boolean, por defecto `true`): `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.
- `settings.agent.language` (string, por defecto `en`): El idioma en el que escribe el agente, como etiqueta BCP 47 (`en`, `es`).
- `settings.agent.auto_pull_requests` (string, por defecto `off`): Solo en Sypnia Cloud. `high_confidence` abre un pull request por su cuenta cuando un análisis es `high`. Uno de: `off`, `high_confidence`.

**Petición:**

```bash
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"]}}}'
```

**Respuesta (200):**

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

- `400` `invalid_request`: Un ajuste está fuera de rango o no existe. `param` lo nombra, por ejemplo `settings.replay.sample_rate`.
- `404` `not_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:**

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

**Errores:**

- `400` `invalid_request`: Falta `confirm` o no es el slug del proyecto.
- `403` `cloud_managed`: La petición llegó a Sypnia Cloud. Borra los proyectos en la app.
- `404` `not_found`: No existe ese proyecto.

## Listar llaves de ingesta

`GET /v1/keys` \[Motor, Nube]

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

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

**Respuesta (200):**

```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` \[Motor, Nube]

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](https://docs.sypnia.com/es/api/errors-limits-pagination#idempotency).

**Cuerpo:**

- `name` (string, hasta 80 caracteres, obligatorio): Para qué es la llave.
- `rate_limit_per_minute` (integer, 10 a 6,000, opcional, por defecto `600`): 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.

**Petición:**

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

**Respuesta (201):**

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

- `409` `limit_reached`: El proyecto ya tiene 20 llaves sin revocar.

## Revocar una llave de ingesta

`DELETE /v1/keys/{key_id}` \[Motor, Nube]

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

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

**Errores:**

- `404` `not_found`: Ninguna llave del proyecto tiene este id.
- `409` `conflict`: 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` \[Motor, Nube]

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

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

**Respuesta (200):**

```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` \[Motor, Nube]

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:

| Permiso  | Qué permite                                                                                                                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `read`   | Leer 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 |
| `replay` | Traer grabaciones y capturas de página. Muestran la página como la vio la persona                                                                                                                |
| `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                |

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](https://docs.sypnia.com/es/api/errors-limits-pagination#idempotency).

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

```bash
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"]}'
```

**Respuesta (201):**

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

- `400` `invalid_request`: `scopes` está vacío o tiene un valor distinto de `read`, `replay`, `admin`; o `expires_at` está en el pasado.
- `409` `limit_reached`: El proyecto ya tiene 50 tokens sin revocar.

## Revocar un token de API

`DELETE /v1/tokens/{token_id}` \[Motor, Nube]

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

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

**Errores:**

- `404` `not_found`: Ningún token del proyecto tiene este id.

## Traer el uso y los límites

`GET /v1/usage` \[Motor, Nube]

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.

| Contador        | Qué cuenta como uno                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `events`        | Un 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 |
| `replays`       | Una sesión que tiene grabación                                                                                                                                                            |
| `analyses`      | Una corrida del agente sobre un problema. Se cuenta por día                                                                                                                               |
| `pull_requests` | Un 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:**

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

**Respuesta (200):**

```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](https://docs.sypnia.com/es/api/errors-limits-pagination).
