Ab dem Solo-Tarif können Ihre Skripte, Ihre CI und Ihre KI-Assistenten über eine API die Ergebnisse Ihrer Domains lesen und Audits starten. Sie antwortet in JSON, und das neueste Audit lässt sich auch als SARIF lesen, das Format, das Code-Scanning-Tools verstehen. Die GitHub Action und der MCP-Server bauen darauf auf.

Einen Schlüssel erstellen

Öffnen Sie Einstellungen und suchen Sie die Karte API-Schlüssel.
Geben Sie dem Schlüssel einen Namen, der sagt, wo er verwendet wird, etwa „GitHub Actions“.
Haken Sie Kann Audits starten nur an, wenn dieser Schlüssel Audits starten muss (ein CI-Job, der bei jedem Deployment eines startet). Lassen Sie es bei einem Schlüssel, der nur liest, frei.
Klicken Sie auf Schlüssel erstellen und kopieren Sie den Schlüssel sofort: Er beginnt mit pc_ und wird nur einmal angezeigt. Speichern Sie ihn als Secret in Ihrer CI oder in Ihrem Passwortmanager.

Nur Inhaber und Administratoren können Schlüssel erstellen und widerrufen. Die Karte listet jeden Schlüssel mit seinen ersten Zeichen, was er darf, wann er erstellt und wann er zuletzt verwendet wurde. Widerrufen sperrt einen Schlüssel sofort. Wird ein Mitglied aus dem Arbeitsbereich entfernt, werden die von ihm erstellten Schlüssel mit widerrufen.

Die API aufrufen

Die API ist unter https://app.perimetry.cloud erreichbar. Senden Sie den Schlüssel bei jeder Anfrage im Header Authorization, nie in der Adresse:

Authorization: Bearer pc_…

Jede Antwort enthält Perimetry-Api-Version: 1 und den Stand Ihres stündlichen Kontingents (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Version 1 erhält nur neue Felder hinzu: Nichts wird umbenannt oder entfernt, ein heute geschriebenes Skript funktioniert also weiter.

Überall, wo eine Anfrage :id erwartet, können Sie die ID der Domain oder ihren Namen (example.com) angeben.

Die Anfragen zur Domain, zu den Befunden und zum Vergleich nehmen lang=de oder lang=fr an, damit Titel, Erklärungen und Behebungen der Befunde auf Deutsch oder Französisch kommen; standardmäßig auf Englisch.

Anfrage	Was sie tut
`GET /api/v1/me`	Der Arbeitsbereich, der Tarif, was der Schlüssel darf und was vom stündlichen Kontingent übrig ist.
`GET /api/v1/domains`	Die Domains des Arbeitsbereichs: ID, Name, Status, Kunde, Punktzahl, Bewertung, offene Befunde nach Schweregrad, Daten des letzten und nächsten Audits, Link zum Bericht. `?name=example.com` behält eine.
`GET /api/v1/domains/:id`	Eine Domain: ihre Punktzahl, ihr letztes Audit mit der Änderung der Punktzahl seit dem vorherigen, neue und behobene Befunde und die drei zuerst zu behebenden Befunde.
`GET /api/v1/domains/:id/findings`	Die offenen Befunde des neuesten Audits, die schwerwiegendsten zuerst, jeweils mit Behebung, kopierfertigen DNS-Einträgen und den Anforderungen aus NIS2, Cyber Essentials und ISO 27001. Optionen: `min_severity`, `include_accepted=1`, `limit`, `lang`.
`GET /api/v1/domains/:id/compare`	Was sich seit dem vorherigen Audit geändert hat: Punktzahl vorher und nachher, hinzugekommene, behobene oder im Schweregrad geänderte Befunde, Hosts, Ports, Zertifikate, Lookalike-Domains.
`GET /api/v1/domains/:id/audits`	Der Verlauf der Audits: Datum, Punktzahl, Bewertung, Zählungen (`limit`, höchstens 100).
`GET /api/v1/domains/:id/latest`	Das neueste Audit vollständig, mit seinen Befunden und den akzeptierten; `?format=sarif` für SARIF.
`POST /api/v1/domains/:id/audit`	Startet ein Audit einer verifizierten Domain (Schlüssel, der Audits starten darf). Antwortet mit 202 und einem Lauf, den Sie verfolgen können.
`GET /api/v1/runs/:id`	Der Stand dieses Audits: `queued`, `running` (mit Fortschritt), `done` (neue Punktzahl, vorherige Punktzahl, Änderung) oder `failed`.

Jedes Feld jeder Antwort, die Fehlercodes und die OpenAPI-3.1-Spezifikation zum Herunterladen (für Postman, Code-Generatoren und Automatisierungswerkzeuge) finden Sie in der API-Referenz.

Beispiele

Ihre Domains auflisten:

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" https://app.perimetry.cloud/api/v1/domains

Die schwerwiegenden Befunde einer Domain, mit ihren Behebungen, auf Deutsch:

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" \
  "https://app.perimetry.cloud/api/v1/domains/example.com/findings?min_severity=high&lang=de"

Was sich seit dem vorherigen Audit geändert hat:

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" https://app.perimetry.cloud/api/v1/domains/example.com/compare

Ein Audit starten und es bis zum Abschluss verfolgen:

curl -X POST -H "Authorization: Bearer $PERIMETRY_API_KEY" https://app.perimetry.cloud/api/v1/domains/example.com/audit
# → {"apiVersion":1,"queued":true,"run":{"id":"6f1c…","status":"queued",…}}
curl -H "Authorization: Bearer $PERIMETRY_API_KEY" https://app.perimetry.cloud/api/v1/runs/6f1c…

Das neueste Audit als SARIF, für ein Code-Scanning-Tool:

curl -H "Authorization: Bearer $PERIMETRY_API_KEY" -o perimetry.sarif \
  "https://app.perimetry.cloud/api/v1/domains/example.com/latest?format=sarif"

Grenzen

Aufrufe pro Stunde, für den ganzen Arbeitsbereich: 300 im Solo-Tarif, 1.200 im Agency-Tarif, 3.600 im Agency-Plus-Tarif. Darüber hinaus antwortet die API mit 429 und einem Header Retry-After, bis die nächste Stunde beginnt.
Audits auf Anfrage: dieselbe Regel wie bei der Schaltfläche Jetzt auditieren (eines pro Stunde und Domain im Solo-Tarif, so oft wie nötig in den Agency-Tarifen) und über die API eines alle 15 Minuten pro Domain. Wartet oder läuft bereits ein Audit der Domain, folgt eine neue Anfrage diesem, statt ein weiteres zu starten.

Fehler

Fehler antworten in JSON mit einer Meldung und einem stabilen Code: {"error": "…", "code": "…"}.

400 invalid_parameter: Ein Parameter hat einen Wert, den die API nicht annimmt, etwa min_severity=urgent; die Meldung nennt die zulässigen Werte.
401 unauthorized: Der Schlüssel fehlt, ist fehlerhaft, widerrufen oder unbekannt.
403 plan_excludes_api: Der Tarif des Arbeitsbereichs enthält die API nicht. insufficient_scope: Der Schlüssel darf keine Audits starten.
404 not_found: Die Domain gehört nicht zu diesem Arbeitsbereich; no_audit: Sie hat noch kein Audit.
409 not_verified: Ein Audit wurde für eine nicht verifizierte Domain angefordert.
429 rate_limited: Das stündliche Kontingent ist erreicht; audit_too_soon: Ein Audit dieser Domain auf Anfrage lief vor zu kurzer Zeit; too_many_failures: Aus Ihrem Netz kamen in fünfzehn Minuten sechzig Anfragen mit falschem Schlüssel. In jedem Fall gibt Retry-After die Wartezeit in Sekunden an.

Das Protokoll

Jeder Aufruf wird 90 Tage lang protokolliert: Zeitpunkt, Schlüssel, Route (nie die Parameter) und Antwort. Inhaber und Administratoren sehen die neuesten unter Letzte API-Aufrufe in der Karte der API-Schlüssel. Jedes über die API gestartete Audit erscheint außerdem in der Aktivität des Arbeitsbereichs, mit dem Schlüssel, der es gestartet hat.

Ideen

Ein Deployment scheitern lassen, wenn die Punktzahl sinkt: siehe Perimetry Cloud in Ihrer CI.
Claude oder einen anderen Assistenten zu Ihren Domains befragen: siehe Der MCP-Server.
Die Punktzahlen aller Ihrer Domains in Ihr eigenes Dashboard einspeisen.