Serverseitige Prüf-API - Doku

Die API ist JSON über HTTPS. Zwei Adressen zählen: Der Browser ruft puzzle auf, Ihr Server siteverify.
Beide liegen unter /api/v1/;
die Kurzformen /api/puzzle und /api/verify führen zu denselben Funktionen.

Anmeldung

Serveraufrufe tragen den API-Key im Header X-API-Key.
API-Keys werden in Ihrem Konto angelegt, einmal angezeigt und bei uns als Hash gespeichert.
Ein Schlüssel prüft die Antworten aller Sitekeys Ihres Kontos.
Behandeln Sie ihn wie ein Passwort;
gerät er nach außen, widerrufen Sie ihn und legen einen neuen an.

HTTP

X-API-Key: ck_YOUR_API_KEY

POST /api/v1/siteverify

Parameter	Typ	Beschreibung
`response`	string	Pflicht. Der Wert des versteckten Felds (cdp-captcha-solution).
`sitekey`	string	Optional. Wenn angegeben, muss die Antwort zu diesem Sitekey gehören.

Parameter kommen als JSON-Body oder als Formulardaten.
Beispiel:

cURL

curl -X POST 'https://cdpcaptcha.com/api/v1/siteverify' \
  -H 'X-API-Key: ck_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"response": "…", "sitekey": "YOUR_SITEKEY"}'

Erfolgreiche Prüfung

JSON

{
  "success": true,
  "data": {
    "verification_id": "cv_8e1d0a2c4b6f9a11",
    "challenge": {
      "solved_at": "2026-10-13T10:12:04Z",
      "issued_at": "2026-10-13T10:11:58Z",
      "sitekey": "YOUR_SITEKEY",
      "difficulty_bits": 14
    }
  }
}

Fehlgeschlagene Prüfung

JSON

{
  "success": false,
  "error": {
    "code": "response_duplicate",
    "detail": "The response was already used."
  }
}

Fehlercodes

Code	HTTP	Bedeutung
`auth_required`	401	Der Header X-API-Key fehlt.
`auth_invalid`	401	Der API-Key ist unbekannt oder widerrufen.
`sitekey_invalid`	400	Der Sitekey ist unbekannt, widerrufen oder gehört zu einem anderen Konto.
`response_missing`	400	Kein Parameter response.
`response_invalid`	200	Falsches Format, ungültige Signatur, unbekanntes Rätsel oder falsche Lösung.
`response_timeout`	200	Das Rätsel ist abgelaufen.
`response_duplicate`	200	Die Antwort wurde bereits benutzt.
`bad_request`	400	Fehlerhafte Anfrage (zum Beispiel eine Antwort größer als 16 KB).
`method_not_allowed`	405	Bitte POST verwenden.

Status 200 mit success: false ist die normale Antwort auf ein schlechtes Token. Entscheiden Sie anhand des Felds success, nie allein anhand des Statuscodes. Ein 401 oder 400 bedeutet, dass Ihr Einbau falsch eingestellt ist.

Wenn die API nicht erreichbar ist

Erreicht Ihr Server die Adresse gar nicht (Zeitüberschreitung, Verbindungsfehler), entscheiden Sie bewusst: Jedes Formular während eines Ausfalls abzulehnen, kann schlimmer sein, als etwas Spam anzunehmen.
Der PHP-Client hat dafür die Option fail_open und protokolliert den Übertragungsfehler.
Ein ungültiges Token nimmt er nie an.

GET /api/v1/puzzle

Wird vom Widget aufgerufen.
Selbst rufen Sie es normalerweise nie auf.

Parameter	Beschreibung
`sitekey`	Pflicht.
`difficulty`	Wird nur für den Playground-Sitekey berücksichtigt.

JSON

{
  "success": true,
  "data": {
    "puzzle": "AQ4IAGjs…",
    "bits": 14,
    "count": 8,
    "expires_at": 1760350318,
    "difficulty": 4,
    "mode": "zero-click"
  }
}

Fehler: sitekey_missing / sitekey_invalid (400), rate_limited (429).
Die Antwort trägt CORS-Header für die beim Sitekey erlaubten Herkünfte;
eine leere Liste erlaubt jede Herkunft.

GET /api/v1/health

JSON

{ "ok": true, "version": "1.0.0" }