API

Flujos de trabajo

Abrir una incidencia, programar un mantenimiento, cambiar el estado de un componente y crear un monitor, paso a paso con curl.

Última actualización:

Incidencia: abrir, actualizar, cerrar

Una incidencia pasa por tres llamadas. Todas necesitan el scope incidents con permiso de escritura.

  1. incident:open abre la incidencia con un título, un primer texto y una gravedad (minor, major o critical; sin indicarla, minor). Con componentIds vinculas los componentes afectados. La respuesta contiene el nuevo ID en data.id.
  2. incident:post-update añade una actualización. Con newStatus fijas el estado: investigating, identified o monitoring.
  3. incident:resolve cierra la incidencia con un texto final.
shellAbrir una incidencia
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:open",
  "payload": {
    "title": "Elevated API latency",
    "body": "We are investigating elevated response times.",
    "severity": "major",
    "componentIds": [
      "<component-id>"
    ]
  }
}'
shellPublicar una actualización con un nuevo estado
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:post-update",
  "payload": {
    "incidentId": "<incident-id>",
    "body": "A slow database query is the cause. A fix is rolling out.",
    "newStatus": "identified"
  }
}'
shellCerrar una incidencia
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:resolve",
  "payload": {
    "incidentId": "<incident-id>",
    "body": "Response times are back to normal."
  }
}'

Mantenimiento: programar, iniciar, completar o cancelar

Los mantenimientos necesitan el scope maintenance con permiso de escritura. maintenance:schedule crea la ventana, con inicio y fin como marcas de tiempo ISO 8601. La respuesta contiene el ID en data.id.

shellProgramar un mantenimiento
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:schedule",
  "payload": {
    "title": "Database upgrade",
    "body": "The API is read-only during the upgrade.",
    "scheduledStart": "2026-11-10T02:00:00Z",
    "scheduledEnd": "2026-11-10T03:00:00Z",
    "componentIds": [
      "<component-id>"
    ]
  }
}'

Después controlas el mantenimiento con maintenance:start, maintenance:complete o maintenance:cancel. Las tres esperan el id. La version es opcional: si la envías, léela de maintenance:detail con el id. Si la versión está desactualizada, la API rechaza la llamada con 409 y el código version_conflict.

shellIniciar un mantenimiento
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:start",
  "payload": {
    "id": "<maintenance-id>",
    "version": 1
  }
}'
shellCompletar un mantenimiento
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:complete",
  "payload": {
    "id": "<maintenance-id>",
    "version": 1
  }
}'
shellCancelar un mantenimiento programado
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:cancel",
  "payload": {
    "id": "<maintenance-id>",
    "version": 1
  }
}'

La API rechaza las transiciones no válidas, por ejemplo iniciar un mantenimiento que ya está completado.

Componente: crear y fijar el estado

Los componentes necesitan el scope components con permiso de escritura. component:create crea un componente y devuelve su ID en data.id. Un componente nuevo empieza en operational.

shellCrear un componente
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:component:create",
  "payload": {
    "name": "API",
    "description": "Public HTTP API"
  }
}'

El estado se cambia con component:update. Además de id y los cambios en changes, la llamada necesita la version actual del componente. La obtienes con component:detail y el id. Tras crearlo vale 1 y sube uno con cada cambio. Con una version obsoleta, la API rechaza el cambio.

shellPoner un componente en caída grave
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:component:update",
  "payload": {
    "id": "<component-id>",
    "version": 1,
    "changes": {
      "status": "major-outage"
    }
  }
}'
operational
Funciona con normalidad.
degraded-performance
Limitado, por ejemplo lento.
partial-outage
Caída parcial.
major-outage
Caída grave.
under-maintenance
En mantenimiento.

Así, un pipeline de despliegue puede poner un componente en under-maintenance antes del despliegue y devolverlo a operational después.

Monitor: crear y comprobar de inmediato

Los monitores necesitan el scope monitors con permiso de escritura. monitor:create crea un monitor de disponibilidad. kind elige el tipo de comprobación: http, keyword, ssl-expiry, tcp-port o heartbeat. El intervalo en intervalSeconds es un texto con uno de estos valores: "60", "300", "600" o "1800". Con componentId vinculas un componente que pasa automáticamente a caída grave cuando falla.

shellCrear un monitor HTTP con un componente vinculado
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:monitor:create",
  "payload": {
    "name": "API health",
    "kind": "http",
    "url": "https://api.example.com/health",
    "intervalSeconds": "300",
    "componentId": "<component-id>",
    "enabled": true
  }
}'

monitor:check-now comprueba un monitor de inmediato y devuelve el resultado en data.up. La llamada solo guarda un punto de medición. Los componentes, las incidencias y las notificaciones solo los cambia la comprobación regular.

shellComprobar un monitor de inmediato
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:monitor:check-now",
  "payload": {
    "monitorId": "<monitor-id>"
  }
}'

Leer un registro: detail

Además de las listas, cada scope con acceso de lectura ofrece una llamada :detail que devuelve un registro por su id. También devuelve la version actual que necesitan los cambios.

shellLeer una incidencia
curl -X POST https://status.example.com/api/query \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:query:incident:detail",
  "payload": {
    "id": "<incident-id>"
  }
}'