API

Les clés API à portée définie donnent à vos pipelines l’API REST complète. Vous les créez dans l’application, sous Intégrations, puis Clés API (owners et admins), et vous les envoyez comme bearer token :

Authorization: Bearer pst_...

Une clé appartient à une seule organisation et porte des scopes explicites, chacun en :read ou :write. Vous pouvez restreindre une clé davantage, à des projets choisis ou à des monitors individuels. Révocation et expiration prennent effet dès la requête suivante.

Ce qu’une clé peut faire

Chaque opération authentifiée du contrat public accepte les clés API : 67 opérations, dont 44 en écriture.

Domaine	Opérations	Scopes
Monitors	créer, modifier, supprimer, checks, séries temporelles	monitors:read, monitors:write
Incidents	créer, acquitter, résoudre, notes, post-mortems, curation des indisponibilités	incidents:read, incidents:write
Pages de statut	créer, modifier, archiver, monitors, domaines, accès	status-pages:read, status-pages:write
Fenêtres de maintenance	créer, modifier, annuler, supprimer	maintenance:read, maintenance:write
Webhooks	créer, modifier, tester, renouveler le secret, supprimer	webhooks:read, webhooks:write
Projets	créer, lister, renommer, supprimer	projects:read, projects:write
Organisation	renommer, membres, rôles, invitations	org:read, org:write
Astreinte	astreinte en cours, équipe, réglages	on-call:read, on-call:write
Agents hôtes	lister, retirer	agents:read, agents:write

Un scope d’écriture implique la lecture de la même ressource, jamais d’une ressource à l’autre. Six opérations supplémentaires servent pages de statut publiques, badges, flux, logos et abonnements sans aucune clé.

Les garde-fous de chaque clé

• Une clé agit avec le rôle de son créateur. La personne qui a créé la clé doit encore être membre et porter le rôle que l’opération exige, et les scopes n’accordent jamais un rôle supérieur.
• Les ressources de l’organisation exigent une clé à l’échelle de l’organisation. Une clé restreinte à des projets ou à des monitors atteint exactement ceux-là, et les listes de projets sont filtrées en conséquence.
• Créer une autre organisation demande le scope distinct org:create, une clé à l’échelle de l’organisation et un créateur qui est actuellement owner. La clé reste liée à son organisation d’origine.
• La gestion des clés reste dans la session navigateur, avec la connexion au compte et la facturation. Une clé qui a fuité utilise ce que ses scopes permettent et ne se fabrique jamais de successeur.
• Chaque écriture réussie est enregistrée, avec la clé et la personne qui l’a créée.

Bon à savoir

• Supprimer un monitor est définitif. DELETE /monitors/{monitor_id} supprime le monitor avec ses incidents. Pour retirer un service et garder son registre, archivez-le avec archive_monitor via MCP.
• Les intervalles descendent jusqu’au plancher de votre formule, y compris 15 s avec Command et 10 s avec Enterprise, et montent jusqu’à 24 heures. Une valeur sous le plancher est relevée au plancher. Le formulaire web propose de 30 secondes à 1 heure.
• Les mêmes clés fonctionnent pour MCP. Les scopes monitors et incidents activent les outils MCP correspondants, et status-pages:read ajoute list_status_pages.

La référence complète

La référence documente les 73 opérations sur 52 chemins du contrat public, version 1.0.0-beta.1. Elle est générée au build depuis le contrat embarqué, avec les paramètres, le corps de requête et chaque réponse documentée, schémas dépliés. Vous trouvez les pages de référence dans la barre latérale sous API reference, en anglais comme le contrat lui-même. La spécification est téléchargeable sous openapi.json.

Le produit sert le même contrat, lisible par machine, sur api.perstat.io/openapi.json. La copie d’ici appartient au build que vous lisez, et celle du produit correspond toujours à ce qui est déployé. Si les deux diffèrent, le produit a une longueur d’avance.

Le contrat grandit avec le produit. Les ajouts, comme de nouveaux champs ou endpoints, peuvent arriver à tout moment, et les suppressions ou renommages suivent un délai d’au moins 90 jours, annoncé dans le changelog.