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

  1. Schlüssel anlegen unter Einstellungen → API. Er wird einmal angezeigt.
  2. Domain eintragen und nachweisen — wir prüfen nur Domains, die dir gehören.
  3. 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.txt mit 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 Credit
  • crawlability – robots.txt und Sitemap1 Credit
  • platform – Plattform-Prüfungen1 Credit
  • subpages – Unterseiten5 Credits
  • mobile – Browser-Messung (mobil)3 Credits
  • desktop – 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

Fehlercodes der API
StatusCode Bedeutung
401unauthorizedKein gültiger Schlüssel im Authorization-Kopf.
403plan_without_apiDer Tarif des Kontos enthält die API nicht.
403domain_not_verifiedDie Adresse gehört zu keiner bestätigten Domain des Kontos.
402insufficient_creditsDas Guthaben deckt die Analyse nicht, laufende Analysen mitgezählt.
422invalid_urlDie Adresse ist unbrauchbar oder zeigt nicht ins öffentliche Netz.
422no_checksKeine der gewählten Prüfungen ist im Tarif enthalten.
429rate_limitedZu 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.