Für Entwickler
Die Stackpaper-API
Analysen aus der eigenen Pipeline oder dem eigenen Dashboard starten und die Befunde als JSON lesen — dieselbe Analyse wie auf der Website, mit denselben Belegen.
In drei Schritten
- Schlüssel anlegen unter Einstellungen → API. Er wird einmal angezeigt.
- Domain eintragen und nachweisen — wir prüfen nur Domains, die dir gehören.
- Analyse starten und das Ergebnis abfragen. Bezahlt wird aus dem Credit-Guthaben.
Die API gehört zum Tarif Band. Ein Schlüssel aus einem kleineren Tarif bleibt gültig und funktioniert, sobald gewechselt wird.
Anmeldung
Jede Anfrage trägt den Schlüssel im Kopf Authorization: Bearer sp_…. Alle Adressen beginnen mit https://stackpaper.de/api/v1. Antworten sind JSON; Fehler tragen ein Feld error mit einem festen Code und eine verständliche message.
Lesen ist auf 120 Anfragen pro Minute begrenzt, das Starten von Analysen auf 10 pro Minute und 200 pro Tag.
Domain nachweisen
POST /domains mit {"host": "example.com"} antwortet mit einem Token und zwei Wegen — einer genügt:
- DNS: ein TXT-Eintrag auf der Domain mit dem Wert
stackpaper-verify=<token> - Datei:
https://example.com/.well-known/stackpaper-verify.txtmit dem Token als Inhalt
Danach POST /domains/{id}/verify. Der Nachweis gilt für die Domain und alle Unterdomains.
Analyse starten
Anfrage
curl -X POST https://stackpaper.de/api/v1/analyses \
-H "Authorization: Bearer sp_DEIN_SCHLÜSSEL" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/", "checks": ["page", "mobile"]}'Antwort (202)
{
"data": {
"id": "MTpMig8bsockzKzCgnE0OFLpJ4qVNSauMXCIYvdi6LCp",
"url": "https://example.com/",
"status": "queued",
"checks": ["page", "mobile"],
"credits": 4,
"result_url": "https://stackpaper.de/analysen/MTpMig8…"
}
} Eine Analyse dauert Minuten. Frage sie ab, bis status auf completed oder failed steht:
curl https://stackpaper.de/api/v1/analyses/MTpMig8… -H "Authorization: Bearer sp_DEIN_SCHLÜSSEL"Antwort nach dem Ende
{
"data": {
"status": "completed",
"credits": 4,
"failed_checks": [],
"findings": [
{
"rule": "SEC-HTTP-001",
"category": "security",
"severity": "medium",
"title": "Strict-Transport-Security-Header fehlt",
"summary": "Die Website wird über HTTPS ausgeliefert, sendet aber …",
"recommendation": "Lass den Header „Strict-Transport-Security“ setzen …",
"evidence": {
"metric": "header_present:strict-transport-security",
"value": false,
"unit": null,
"items": []
}
}
]
}
} Prüfungen, die nicht laufen konnten, stehen in failed_checks; ihre Befunde fehlen dann einfach. Jeder Befund trägt den Messwert, auf dem er beruht.
Prüfungen und Preise
checks wählt aus, was laufen soll; ["all"] ist die Voreinstellung und kostet im Tarif Band 14 Credits. Abgezogen wird erst, wenn die Analyse ein Ergebnis liefert — eine gescheiterte kostet nichts.
page– Startseite (Sicherheit, SEO, Technik)1 Creditcrawlability– robots.txt und Sitemap1 Creditplatform– Plattform-Prüfungen1 Creditsubpages– Unterseiten5 Creditsmobile– Browser-Messung (mobil)3 Creditsdesktop– Browser-Messung (Desktop)3 Credits
Adressen
GET /accountTarif, Guthaben, Limits und der Preis je Prüfung.GET /domainsDie Domains des Kontos und ihr Stand.POST /domainsEine Domain eintragen; die Antwort enthält beide Nachweise.POST /domains/{id}/verifyDen Nachweis prüfen. Fünf Prüfungen pro Minute.POST /analysesEine Analyse starten. Antwortet sofort mit ihrer Adresse.GET /analyses/{id}Stand der Analyse, nach dem Ende mit allen Befunden.
Fehler
| Status | Code | Bedeutung |
|---|---|---|
| 401 | unauthorized | Kein gültiger Schlüssel im Authorization-Kopf. |
| 403 | plan_without_api | Der Tarif des Kontos enthält die API nicht. |
| 403 | domain_not_verified | Die Adresse gehört zu keiner bestätigten Domain des Kontos. |
| 402 | insufficient_credits | Das Guthaben deckt die Analyse nicht, laufende Analysen mitgezählt. |
| 422 | invalid_url | Die Adresse ist unbrauchbar oder zeigt nicht ins öffentliche Netz. |
| 422 | no_checks | Keine der gewählten Prüfungen ist im Tarif enthalten. |
| 429 | rate_limited | Zu viele Anfragen; der Kopf Retry-After nennt die Wartezeit. |
Was die API nicht tut
Sie ändert nichts an deiner Website und prüft keine fremden Domains. Änderungsvorschläge im Code entstehen weiterhin nur über die Oberfläche, nach ausdrücklicher Freigabe.