API

API-Schlüssel mit Scopes geben Ihren Pipelines die vollständige REST-API. Sie legen die Schlüssel in der App unter Integrationen, dann API-Schlüssel an (Owner und Admin) und schicken sie als Bearer-Token mit:

Authorization: Bearer pst_...

Ein Schlüssel gehört zu genau einer Organisation und trägt ausdrückliche Scopes, jeweils als :read oder :write. Enger geht immer: Sie begrenzen einen Schlüssel auf ausgewählte Projekte oder auf einzelne Monitore. Widerruf und Ablauf greifen bei der nächsten Anfrage.

Was ein Schlüssel kann

Jeder authentifizierte Vorgang im öffentlichen Vertrag nimmt API-Schlüssel an: 67 Vorgänge, davon 44 schreibend.

Bereich	Vorgänge	Scopes
Monitore	anlegen, ändern, löschen, Checks, Zeitreihen	monitors:read, monitors:write
Incidents	anlegen, quittieren, schließen, Notizen, Post-mortems, Ausfallzeit kuratieren	incidents:read, incidents:write
Statusseiten	anlegen, ändern, archivieren, Monitore, Domains, Zugang	status-pages:read, status-pages:write
Wartungsfenster	anlegen, ändern, beenden, löschen	maintenance:read, maintenance:write
Webhooks	anlegen, ändern, testen, Secret rotieren, löschen	webhooks:read, webhooks:write
Projekte	anlegen, auflisten, umbenennen, löschen	projects:read, projects:write
Organisation	umbenennen, Mitglieder, Rollen, Einladungen	org:read, org:write
Rufbereitschaft	aktueller Dienst, Besetzung, Einstellungen	on-call:read, on-call:write
Host-Agenten	auflisten, entfernen	agents:read, agents:write

Wer schreiben darf, darf dieselbe Ressource auch lesen, nie über Ressourcen hinweg. Sechs weitere Vorgänge liefern öffentliche Statusseiten, Badges, Feeds, Logos und Abonnements ganz ohne Schlüssel.

Schutz, der in jedem Schlüssel steckt

• Ein Schlüssel handelt mit der Rolle seines Erstellers. Die Person, die ihn angelegt hat, muss noch Mitglied sein und die Rolle tragen, die der Vorgang verlangt. Scopes verleihen nie eine höhere Rolle.
• Organisationsweite Ressourcen brauchen einen organisationsweiten Schlüssel. Ein auf Projekte oder Monitore begrenzter Schlüssel erreicht genau diese, und Projektlisten werden passend gefiltert.
• Eine weitere Organisation anlegen verlangt den eigenen Scope org:create, einen organisationsweiten Schlüssel und einen Ersteller, der gerade Owner ist. Der Schlüssel bleibt an seine ursprüngliche Organisation gebunden.
• Die Schlüsselverwaltung bleibt in der Browser-Sitzung, zusammen mit Anmeldung und Abrechnung. Ein abhandengekommener Schlüssel kann nutzen, was seine Scopes hergeben, und stellt sich niemals selbst einen Nachfolger aus.
• Jeder erfolgreiche schreibende Aufruf wird festgehalten, mit dem Schlüssel und der Person, die ihn angelegt hat.

Gut zu wissen

• Das Löschen eines Monitors ist endgültig. DELETE /monitors/{monitor_id} entfernt den Monitor samt seinen Incidents. Um einen Dienst außer Betrieb zu nehmen und seine Aufzeichnung zu behalten, archivieren Sie ihn mit archive_monitor über MCP.
• Intervalle reichen bis zum Minimum Ihres Tarifs, also auch 15 s bei Command und 10 s bei Enterprise, und bis zu 24 Stunden. Werte unter dem Minimum hebt Perstat auf das Minimum an. Das Webformular bietet 30 Sekunden bis 1 Stunde.
• Dieselben Schlüssel funktionieren für MCP. Die Scopes monitors und incidents schalten die passenden MCP-Werkzeuge frei, und status-pages:read ergänzt list_status_pages.

Die vollständige Referenz

Die Referenz dokumentiert alle 73 Vorgänge auf 52 Pfaden des öffentlichen Vertrags, Version 1.0.0-beta.1. Sie entsteht beim Build aus dem mitgelieferten Vertrag, mit Parametern, Request-Body und jeder dokumentierten Antwort samt aufgeklappten Schemas. Sie finden die Referenzseiten in der Seitenleiste unter API reference, auf Englisch wie der Vertrag selbst. Die Spezifikation steht unter openapi.json zum Download bereit.

Das Produkt liefert denselben Vertrag maschinenlesbar unter api.perstat.io/openapi.json aus. Die Kopie hier gehört zu dem Build, den Sie gerade lesen, und die Kopie des Produkts entspricht immer dem, was ausgerollt ist. Weichen beide ab, ist das Produkt voraus.

Der Vertrag wächst mit dem Produkt. Ergänzungen wie neue Felder und Endpunkte kommen jederzeit hinzu, und Entfernungen oder Umbenennungen folgen einer Ankündigungsfrist von mindestens 90 Tagen im Changelog.