# Disponibilidad

> Crea comprobaciones de disponibilidad, lee su estado y sus resultados, y mira cuándo dejó de responder tu app.

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/uptime/

Para agentes: Referencia de los endpoints de disponibilidad de la API de Sypnia: crear, listar, actualizar y borrar comprobaciones, y leer sus resultados y caídas.

Una comprobación de disponibilidad es una petición que el motor le hace a una URL tuya cada cierto tiempo. Una comprobación queda `down` después de dos fallas seguidas y vuelve a `up` con un éxito. Caerse y volver crean, cada uno, una [alerta](https://docs.sypnia.com/es/api/webhooks).

Un motor alojado por ti comprueba desde donde corre, así que ve tu app desde un solo lugar. Sypnia Cloud comprueba desde tres regiones y da una comprobación por caída cuando al menos dos fallan.

## El objeto comprobación de disponibilidad

**Campos:**

- `id` (string, opcional): `chk_…`.
- `name` (string, opcional)
- `url` (URL, opcional)
- `method` (string, opcional)
- `interval_seconds` (integer, opcional)
- `timeout_ms` (integer, opcional)
- `expected_status` (string, opcional)
- `body_contains` (string o null, opcional)
- `headers` (object, opcional)
- `enabled` (boolean, opcional)
- `status` (string, opcional): `unknown` hasta que corre la primera comprobación. Uno de: `up`, `down`, `paused`, `unknown`.
- `down_since` (timestamp o null, opcional): La primera falla de la caída actual.
- `last_checked_at` (timestamp o null, opcional)
- `last_status_code` (integer o null, opcional): El estado HTTP de la última comprobación. `null` cuando no hubo respuesta.
- `last_response_ms` (integer o null, opcional)
- `last_error` (string o null, opcional): Por qué falló la última comprobación: `timeout`, `dns`, `connection_refused`, `tls`, `status_503`, `body_mismatch`.
- `uptime_24h` (number o null, opcional): Porcentaje de comprobaciones que pasaron en las últimas 24 horas.
- `uptime_30d` (number o null, opcional)
- `created_at` (timestamp, opcional)

## Listar comprobaciones de disponibilidad

`GET /v1/uptime/checks` \[Motor, Nube]

Todas las comprobaciones del proyecto con su estado actual. Es lo que devuelve la herramienta MCP `uptime`.

**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`.
- `status` (string, opcional): Solo comprobaciones en este estado. Uno de: `up`, `down`, `paused`, `unknown`.
- `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://api.sypnia.com/v1/uptime/checks" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "chk_1q9w3e7r5t2y",
      "name": "Shop home",
      "url": "https://shop.example.com/",
      "method": "GET",
      "interval_seconds": 60,
      "timeout_ms": 10000,
      "expected_status": "200-399",
      "body_contains": null,
      "headers": {},
      "enabled": true,
      "status": "up",
      "down_since": null,
      "last_checked_at": "2026-03-12T10:34:00Z",
      "last_status_code": 200,
      "last_response_ms": 184,
      "last_error": null,
      "uptime_24h": 100,
      "uptime_30d": 99.98,
      "created_at": "2026-02-02T09:20:00Z"
    }
  ],
  "next_cursor": null
}
```

## Crear una comprobación de disponibilidad

`POST /v1/uptime/checks` \[Motor, Nube]

Empieza a comprobar una URL. La primera comprobación corre en menos de un minuto. El motor envía el encabezado `User-Agent: Sypnia-Uptime/1.0`, sigue hasta 3 redirecciones y nunca envía cookies. Solo se permiten URLs `http` y `https` en direcciones públicas: una URL que resuelve a una dirección privada o local se rechaza, para que una comprobación no sirva para entrar a tu propia red.

**Autenticación:** 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, opcional): Un nombre para las personas. Obligatorio al crear.
- `url` (URL, hasta 2,000 caracteres, opcional): La URL que se pide. Obligatoria al crear.
- `method` (string, opcional, por defecto `GET`): El método HTTP. Uno de: `GET`, `HEAD`.
- `interval_seconds` (integer, opcional, por defecto `60`): Cada cuánto comprobar. Uno de: `60`, `300`, `900`.
- `timeout_ms` (integer, 1,000 a 30,000, opcional, por defecto `10000`): Una respuesta más lenta que esto es una falla.
- `expected_status` (string, opcional, por defecto `200-399`): Los estados que cuentan como arriba: uno (`200`), un rango (`200-299`) o una lista (`200,204,301`).
- `body_contains` (string, hasta 200 caracteres o null, opcional): Texto que debe traer el cuerpo de la respuesta para contar como arriba. Solo con `GET`. El motor lee los primeros 256 KB.
- `headers` (object, opcional): Hasta 10 encabezados de la petición. Se guardan y se devuelven tal como los envías, así que no pongas secretos aquí.
- `enabled` (boolean, opcional, por defecto `true`): `false` pausa la comprobación.

**Petición:**

```bash
curl -X POST "https://api.sypnia.com/v1/uptime/checks" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop home", "url": "https://shop.example.com/"}'
```

**Respuesta (201):**

```json
{
  "id": "chk_1q9w3e7r5t2y",
  "name": "Shop home",
  "url": "https://shop.example.com/",
  "method": "GET",
  "interval_seconds": 60,
  "timeout_ms": 10000,
  "expected_status": "200-399",
  "body_contains": null,
  "headers": {},
  "enabled": true,
  "status": "unknown",
  "down_since": null,
  "last_checked_at": null,
  "last_status_code": null,
  "last_response_ms": null,
  "last_error": null,
  "uptime_24h": null,
  "uptime_30d": null,
  "created_at": "2026-02-02T09:20:00Z"
}
```

**Errores:**

- `400` `invalid_request`: La URL no es `http` ni `https`, resuelve a una dirección privada, o un campo está fuera de rango. `param` nombra el campo.
- `409` `limit_reached`: El proyecto ya tiene tantas comprobaciones como permite su plan (Sypnia Cloud), o como permite `SYPNIA_QUOTA_UPTIME_CHECKS` (motor).

## Traer una comprobación de disponibilidad

`GET /v1/uptime/checks/{check_id}` \[Motor, Nube]

Una comprobación con su estado actual.

**Autenticación:** Token de API (`read`)

**Parámetros de ruta:**

- `check_id` (string, obligatorio): El id de la comprobación (`chk_…`).

**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/uptime/checks/chk_1q9w3e7r5t2y" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "id": "chk_1q9w3e7r5t2y",
  "name": "Shop home",
  "url": "https://shop.example.com/",
  "method": "GET",
  "interval_seconds": 60,
  "timeout_ms": 10000,
  "expected_status": "200-399",
  "body_contains": null,
  "headers": {},
  "enabled": true,
  "status": "up",
  "down_since": null,
  "last_checked_at": "2026-03-12T10:34:00Z",
  "last_status_code": 200,
  "last_response_ms": 184,
  "last_error": null,
  "uptime_24h": 100,
  "uptime_30d": 99.98,
  "created_at": "2026-02-02T09:20:00Z"
}
```

**Errores:**

- `404` `not_found`: Ninguna comprobación del proyecto tiene este id.

## Actualizar una comprobación de disponibilidad

`PATCH /v1/uptime/checks/{check_id}` \[Motor, Nube]

Cambia los campos que envías y deja los demás. Pon `enabled` en `false` para pausar una comprobación; una comprobación pausada tiene estado `paused` y no crea alertas.

**Autenticación:** Token de API (`admin`)

**Parámetros de ruta:**

- `check_id` (string, obligatorio): El id de la comprobación (`chk_…`).

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

**Cuerpo:**

- `name` (string, hasta 80 caracteres, opcional): Un nombre para las personas. Obligatorio al crear.
- `url` (URL, hasta 2,000 caracteres, opcional): La URL que se pide. Obligatoria al crear.
- `method` (string, opcional, por defecto `GET`): El método HTTP. Uno de: `GET`, `HEAD`.
- `interval_seconds` (integer, opcional, por defecto `60`): Cada cuánto comprobar. Uno de: `60`, `300`, `900`.
- `timeout_ms` (integer, 1,000 a 30,000, opcional, por defecto `10000`): Una respuesta más lenta que esto es una falla.
- `expected_status` (string, opcional, por defecto `200-399`): Los estados que cuentan como arriba: uno (`200`), un rango (`200-299`) o una lista (`200,204,301`).
- `body_contains` (string, hasta 200 caracteres o null, opcional): Texto que debe traer el cuerpo de la respuesta para contar como arriba. Solo con `GET`. El motor lee los primeros 256 KB.
- `headers` (object, opcional): Hasta 10 encabezados de la petición. Se guardan y se devuelven tal como los envías, así que no pongas secretos aquí.
- `enabled` (boolean, opcional, por defecto `true`): `false` pausa la comprobación.

**Petición:**

```bash
curl -X PATCH "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"interval_seconds": 300, "body_contains": "Add to cart"}'
```

**Respuesta (200):**

```json
{
  "id": "chk_1q9w3e7r5t2y",
  "name": "Shop home",
  "url": "https://shop.example.com/",
  "method": "GET",
  "interval_seconds": 300,
  "timeout_ms": 10000,
  "expected_status": "200-399",
  "body_contains": "Add to cart",
  "headers": {},
  "enabled": true,
  "status": "up",
  "down_since": null,
  "last_checked_at": "2026-03-12T10:33:00Z",
  "last_status_code": 200,
  "last_response_ms": 184,
  "last_error": null,
  "uptime_24h": 100,
  "uptime_30d": 99.98,
  "created_at": "2026-02-02T09:20:00Z"
}
```

**Errores:**

- `400` `invalid_request`: Un campo está fuera de rango. `param` lo nombra.
- `404` `not_found`: Ninguna comprobación del proyecto tiene este id.

## Borrar una comprobación de disponibilidad

`DELETE /v1/uptime/checks/{check_id}` \[Motor, Nube]

Detiene la comprobación y borra sus resultados. Las alertas que creó se quedan.

**Autenticación:** Token de API (`admin`)

**Parámetros de ruta:**

- `check_id` (string, obligatorio): El id de la comprobación (`chk_…`).

**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/uptime/checks/chk_1q9w3e7r5t2y" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Errores:**

- `404` `not_found`: Ninguna comprobación del proyecto tiene este id.

## Traer los resultados de una comprobación

`GET /v1/uptime/checks/{check_id}/results` \[Motor, Nube]

La historia de la comprobación: un intervalo por hora con cuántas comprobaciones corrieron, cuántas fallaron y cuánto tardaron las respuestas, más las caídas, cada tramo en el que la comprobación estuvo abajo. Los resultados sueltos se guardan 7 días y los intervalos por hora 400 días.

**Autenticación:** Token de API (`read`)

**Parámetros de ruta:**

- `check_id` (string, obligatorio): El id de la comprobación (`chk_…`).

**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`.
- `since` (string, opcional, por defecto `24h`): Inicio del periodo.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y/results?since=3h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "check_id": "chk_1q9w3e7r5t2y",
  "uptime": 99.44,
  "buckets": [
    {
      "start": "2026-03-12T08:00:00Z",
      "checks": 60,
      "failures": 0,
      "avg_ms": 181,
      "p95_ms": 240
    },
    {
      "start": "2026-03-12T09:00:00Z",
      "checks": 60,
      "failures": 1,
      "avg_ms": 190,
      "p95_ms": 262
    },
    {
      "start": "2026-03-12T10:00:00Z",
      "checks": 33,
      "failures": 0,
      "avg_ms": 184,
      "p95_ms": 251
    }
  ],
  "incidents": []
}
```

**Errores:**

- `404` `not_found`: Ninguna comprobación del proyecto tiene este id.

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