Zum Inhalt springen
RedcheckStartseite
REST-API / Domains

Domains

Jeder Lauf gehört zu einer Domain der Organisation. Wie Sie das Eigentum an einer Domain nachweisen, steht unter Domain verifizieren. Quittierte Befunde einer Domain stehen unter Befunde.

Auflisten

GEThttps://api.red-check.de/v1/domains

q
string
Suche über den Domainnamen.
verification_status
enum
–pending · verified · failed · expired
limit
integer
–
cursor
string
Undurchsichtiger Zeiger aus `next_cursor` der vorigen Seite.

Die Liste ist seitenweise, wie unter Konventionen beschrieben. Ein Schlüssel mit Domain-Einschränkung sieht nur seine Domains.

Ein Eintrag aus items
{
  "id": "3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e",
  "name": "",
  "apex": "",
  "client_name": "",
  "context": "shop",
  "verification_status": "pending",
  "last_scan_at": "2026-09-03T09:14:22Z",
  "open_critical": 0,
  "open_high": 0,
  "last_score": 0
}

Anlegen

POSThttps://api.red-check.de/v1/domains

name
stringPflicht
Ohne Schema, ohne Pfad. `https://` wird toleriert und entfernt.
context
enum
Kontextprofil der Domain. Etiketten: Shop · Broschüre · Anwendung · Intern. Steuert die Eskalation der Schweregrade im Katalog.shop · brochure · saas · internal
client_id
string | null
Kunde aus `/v1/clients`. Hat Vorrang vor `client_name`: Ist beides gesetzt, gilt die Kennung, und der Name wird aus ihr abgeleitet.
client_name
string
Freitext-Zuordnung für Organisationen ohne Kundenverwaltung. Leer = keine Zuordnung.
Anfrage
curl -X POST https://api.red-check.de/v1/domains \
  -H "Authorization: Bearer rc_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example.de",
  "context": "shop",
  "client_id": "3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e"
}'

Abgerechnet wird je Apex, bestimmt über die Public-Suffix-Liste. Eine Subdomain unter einem bereits eingetragenen Apex zählt nicht gegen das Kontingent des Plans. Ist es ausgeschöpft, antwortet die API mit 402 quota_exceeded. Entfernte Domains zählen danach noch 30 Tage mit. Bei Abrechnung je Lauf (Plan Agentur) kosten Domains nichts.

201
Angelegt.
400
Kein gültiger Domainname (`invalid_domain`).
402
Kontingent erschöpft (`quota_exceeded`).
409
Zustand passt nicht (`conflict`, `already_exists`).

Eine Domain lesen

GEThttps://api.red-check.de/v1/domains/{id}

Die Antwort enthält die Felder unten, dazu verifications mit dem Stand der drei Nachweismethoden und pinned_ips mit den Adressen, gegen die aktive Läufe geprüft werden.

id
uuidPflicht
–
name
stringPflicht
–
apex
stringPflicht
–
is_apex
boolean
–
client_id
string | null
Der Kunde aus der Kundenverwaltung der Agentur (`/v1/clients`). Null = keine Zuordnung.
client_name
string
WP-8. Der Kunde einer Agentur, für den diese Domain steht. Leer = keine Zuordnung. Gruppiert Domainliste und Nutzungsabrechnung, ist aber keine Mandantengrenze: Eine Agentur bleibt eine einzige Organisation. Der Name wird zusätzlich zu `client_id` geführt und beim Buchen eines Laufs kopiert, damit eine spätere Umbenennung eine gestellte Rechnung nicht rückwirkend ändert.
billed_until
string | null
Nur nach dem Entfernen gesetzt. Eine entfernte Domain zählt noch 30 Tage als abgerechnete Domain, damit „löschen und eine andere anlegen“ kein Geld spart.
context
enumPflicht
Der wirksame Kontext (gewählt, sonst erkannt, sonst `brochure`).shop · brochure · saas · internal
context_selected
enum | null
–shop · brochure · saas · internal
context_detected
enum | null
–shop · brochure · saas · internal
verification_status
enumPflicht
–pending · verified · failed · expired
verified_method
enum | null
–dns_txt · file · meta
verified_at
string | null
–
verification_expires_at
string | null
–
last_checked_at
string | null
–
billable
boolean
–
last_scan_at
string | null
–
last_scan_id
string | null
–
open_critical
integer
–
open_high
integer
–
last_score
integer | null
Der Score des jüngsten abgeschlossenen Laufs, aus demselben Rollup wie `open_critical` und `open_high`. `null`, solange kein Lauf einen Score hat. Er steht an der Domainzeile, damit eine Liste nicht je Zeile die Läufe abfragen muss.
last_score_provisional
boolean
Ob dieser Score aus einem Lauf mit unvollständiger Prüfabdeckung stammt.
acknowledged_count
integer
Wie viele geltende Quittierungen es für diese Domain gibt.
created_at
string (date-time)
–

Ändern

PATCHhttps://api.red-check.de/v1/domains/{id}

Änderbar sind der Kontext und die Kundenzuordnung.

context
enum | null
Null bedeutet: den erkannten Kontext übernehmen.shop · brochure · saas · internal
client_id
string | null
Null hebt die Zuordnung auf.
client_name
string
–

Für die Zuordnung zu einem Kunden aus der Kundenverwaltung nehmen Sie client_id. Wie Sie Kunden anlegen, steht unter Kunden.

200
Geändert.
400
Eingabe ungültig (`validation_failed`).

Entfernen

DELETEhttps://api.red-check.de/v1/domains/{id}

Läufe und Befunde bleiben erhalten. Die Domain verschwindet aus Listen und Zeitplänen. Solange ein Lauf in Arbeit ist, antwortet die API mit 409 conflict.

204
Entfernt.
400
Eingabe ungültig (`validation_failed`).
409
Ein Lauf ist gerade in Arbeit (`conflict`).

Punkteverlauf

GEThttps://api.red-check.de/v1/domains/{id}/score-history

Liefert den Score jedes Laufs der Domain, älteste zuerst. Gescheiterte Läufe stehen mit score: null darin.

limit
integer
–
scan_id
uuidPflicht
–
status
enumPflicht
`queued` wartend · `leased` einem Worker zugeteilt · `running` läuft · `done` fertig · `failed` fehlgeschlagen · `canceled` abgebrochen · `awaiting_review` wartet auf Prüfer (nur KI-Scan, seit 1.3.0; kein Worker nimmt ihn, Redcheck schließt ihn von Hand ab oder lehnt ihn ab).queued · leased · running · done · failed · canceled · awaiting_review
created_at
string (date-time)Pflicht
–
finished_at
string | null
–
score
integer | null
`null` bei gescheiterten Läufen und bei Läufen ohne gespeicherte Befunde. Sie stehen trotzdem in der Reihe, damit die Kurve eine Lücke nicht als durchgezogene Linie zeichnet.
risk_points
number | null
–
risk_points_acknowledged
number
–
score_provisional
boolean
–
schedule_id
string | null
Der Zeitplan, aus dem der Lauf entstanden ist. `null` bei Ad-hoc-Läufen.

Rechte

Aufrufread_onlystart_scansfull
GET Liste, Domain, Punkteverlaufjajaja
POST anlegen, PATCH ändernneinjaja
DELETE, POST .../pinneinneinnein