API

Las claves de API con scopes dan a tus pipelines la API REST completa. Las creas en la app en Integraciones, luego Claves de API (owner y admin), y las envías como bearer token:

Authorization: Bearer pst_...

Una clave pertenece a una sola organización y lleva scopes explícitos, cada uno como :read o :write. Puedes restringir una clave aún más: a proyectos concretos o a monitores individuales. La revocación y la caducidad surten efecto en la siguiente petición.

Qué puede hacer una clave

Cada operación autenticada del contrato público acepta claves de API: 67 operaciones, 44 de ellas de escritura.

Área	Operaciones	Scopes
Monitores	crear, modificar, borrar, checks, series temporales	monitors:read, monitors:write
Incidentes	crear, confirmar, resolver, notas, post-mortems, curación de caídas	incidents:read, incidents:write
Páginas de estado	crear, modificar, archivar, monitores, dominios, acceso	status-pages:read, status-pages:write
Ventanas de mantenimiento	crear, modificar, cancelar, borrar	maintenance:read, maintenance:write
Webhooks	crear, modificar, probar, rotar secreto, borrar	webhooks:read, webhooks:write
Proyectos	crear, listar, renombrar, borrar	projects:read, projects:write
Organización	renombrar, miembros, roles, invitaciones	org:read, org:write
Guardias	guardia actual, cuadrante, ajustes	on-call:read, on-call:write
Agentes de host	listar, quitar	agents:read, agents:write

Un scope de escritura implica lectura sobre el mismo recurso, nunca de un recurso a otro. Otras seis operaciones sirven páginas de estado públicas, badges, feeds, logotipos y suscripciones sin ninguna clave.

Salvaguardas en cada clave

• Una clave actúa con el rol de quien la creó. Esa persona tiene que seguir siendo miembro y tener el rol que exige la operación, y los scopes nunca conceden un rol superior.
• Los recursos de toda la organización exigen una clave de toda la organización. Una clave restringida a proyectos o monitores alcanza exactamente esos, y las listas de proyectos se filtran en consecuencia.
• Crear otra organización exige el scope propio org:create, una clave de toda la organización y que quien la creó sea owner en ese momento. La clave sigue vinculada a su organización de origen.
• La gestión de claves se queda en la sesión del navegador, junto con el acceso a la cuenta y la facturación. Una clave filtrada puede usar lo que sus scopes permiten y nunca podrá emitirse una sucesora.
• Cada escritura correcta queda registrada, con la clave y la persona que la creó.

Conviene saber

• Borrar un monitor es definitivo. DELETE /monitors/{monitor_id} borra el monitor junto con sus incidentes. Para retirar un servicio y conservar su registro, archívalo con archive_monitor mediante MCP.
• Los intervalos bajan hasta el mínimo de tu plan, también 15 s en Command y 10 s en Enterprise, y suben hasta 24 horas. Un valor por debajo del mínimo sube al mínimo. El formulario web ofrece de 30 segundos a 1 hora.
• Las mismas claves sirven para MCP. Los scopes monitors e incidents activan las herramientas MCP correspondientes, y status-pages:read añade list_status_pages.

La referencia completa

La referencia documenta las 73 operaciones en 52 rutas del contrato público, versión 1.0.0-beta.1. Se genera durante el build a partir del contrato incluido, con parámetros, cuerpo de la petición y cada respuesta documentada, con los esquemas desplegados. Encuentras las páginas de referencia en la barra lateral, en API reference, en inglés como el propio contrato. La especificación se puede descargar en openapi.json.

El producto sirve el mismo contrato, legible por máquinas, en api.perstat.io/openapi.json. La copia de aquí pertenece al build que estás leyendo, y la del producto coincide siempre con lo desplegado. Si difieren, el producto va por delante.

El contrato crece con el producto. Los añadidos, como campos o endpoints nuevos, pueden llegar en cualquier momento, y las retiradas o los cambios de nombre siguen un plazo de al menos 90 días, anunciado en el changelog.