REST-API / Zeitpläne

Zeitpläne

Ein Zeitplan startet Läufe gegen eine Domain in festem Takt, mit denselben Prüfbereichen und Prüfungen wie ein Lauf von Hand. Zeitpläne gibt es ab dem Plan Pro.

Auflisten

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

Anfrage

curl -X GET https://api.red-check.de/v1/schedules \
  -H "Authorization: Bearer rc_live_••••••••"

Die Antwort ist ein Array ohne Seiten. Ein Schlüssel mit Domain-Einschränkung sieht nur die Zeitpläne seiner Domains.

Ein Eintrag

{
  "id": "3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e",
  "domain_id": "3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e",
  "domain": "",
  "cadence": "off",
  "weekday": 0,
  "run_window": "night",
  "tier": "passive",
  "security": false,
  "privacy": false,
  "accessibility": false,
  "state": "active",
  "next_run_at": "2026-09-03T09:14:22Z",
  "automatic": false
}

Anlegen

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

FeldTypBeschreibung

domain_id

uuidPflicht

–

backend_scope_policy

enum

Ausdrückliche Bestätigung der Backend-Beauftragung für die Läufe dieses Zeitplans. Sie wird unabhängig vom Generationsschalter gespeichert, und jeder Lauf erhält eine eigene, beim Start geprüfte Kopie. Ohne Feld gilt 0, auch beim Ändern, damit ältere Clients keine Freigabe erteilen.0 · 1

cadence

enumPflicht

Takt eines Zeitplans. `off` gibt es seit Migration 0065. Vorher hieß „aus" `active: false`, und solange das die einzige Form war, ließ sich nirgends festhalten, welcher Takt eingestellt wäre. Ein abgeschalteter Zeitplan behält seinen Wochentag und weiß beim nächsten Einschalten noch, worauf er eingestellt war. Alte Aufrufer schalten weiterhin mit `active: false` ab; der Server liest das als `off`. Der Wert fehlte hier versehentlich, und das brach den Vertrag. 0065 hat den Bestand umgedeutet: Jeder abgeschaltete Zeitplan trägt seither `cadence = 'off'`, und `GET /v1/schedules` gab ihn heraus, obwohl die Aufzählung ihn nicht kannte. Ein erzeugter Leser wies die Antwort ab.off · daily · weekly · monthly

weekday

integer | null

–

day_of_month

integer | null

–

run_minute

integer | null

Minute und Fenster gehören zusammen, und genau eines von beiden ist der Wunsch. Steht `run_window` im Körper, gilt das Fenster, und die Minute wird daraus gezogen. Steht nur `run_minute` da, gilt die Minute, und das Fenster folgt ihr. In der umgekehrten Reihenfolge würde ein ausdrücklich gesetzter Termin stillschweigend verschoben.

run_window

enum

Die übliche Angabe ab Z01. Ohne Fenster und ohne Minute gilt `night`.night · morning · day · evening

paused_until

string | null

Pause bis einschließlich dieses Tages. Der Wert ist ein Datum ohne Uhrzeit; die API rechnet daraus das Ende dieses Tages in der Zeitzone der Organisation. Fehlt das Feld oder steht `null` da, läuft keine Pause. `state` nimmt der Server hier nicht entgegen, denn der Zustand folgt aus dem Datum: mit Datum `paused`, ohne Datum `active`. `waiting_quota` setzt allein der Läufer, und von außen soll niemand ihn behaupten können.

tier

enumPflicht

Die Stufen, die ein Kunde wählen darf.passive · active

security

boolean

–Vorgabe true

privacy

boolean

Ab Pro. Vorgabe wie bei `CreateScanRequest.privacy`: an bei Abrechnung nach Kontingent ab Pro, aus bei Abrechnung je Lauf (Agentur) und in Free; ausdrücklich `true` in Free ist `plan_upgrade_required` (402).

accessibility

boolean

Ab Pro; `true` in Free ist `plan_upgrade_required` (402).Vorgabe false

full_site

boolean

Wie `CreateScanRequest.full_site`: Mit `privacy` oder `accessibility` gilt `true`, auch ohne Angabe. Der gespeicherte Zeitplan trägt dann den Wert, mit dem seine Läufe tatsächlich laufen werden, auch wenn das Formular etwas anderes geschickt hat.Vorgabe false

path_prefix

string

Wie `CreateScanRequest.path_prefix`, mit denselben Regeln und denselben Absagen.Vorgabe ""

cve_include_possible

boolean

–Vorgabe false

nuclei_full

boolean

–Vorgabe false

context

enum | null

Wie `CreateScanRequest.context`: übersteuert den Kontext der Domain, hier für jeden Lauf dieses Zeitplans. Bei `null` nehmen die Läufe den Kontext, der zum Zeitpunkt des Laufs an der Domain steht. Fehlt das Feld, bleibt beim Ändern der gespeicherte Wert stehen, und beim Anlegen gilt `null`, weil ältere Aufrufer das Feld nicht kennen.shop · brochure · saas · internal

active

boolean

Veraltet, wird aber weiterhin verstanden. Seit 0065 ist „aus" der Takt `off`; am Zeitplan ist `active` nur noch die abgeleitete Auskunft `cadence <> 'off' and state = 'active'`. Ein Körper mit `active: false` und einem echten Takt gilt als Abschalten und setzt den Takt auf `off`; der Wochentag bleibt dabei stehen. Neue Aufrufer setzen stattdessen `cadence: off`. Zusammen mit `paused_until` hat das Feld keine Wirkung: Eine Pause schaltet nicht ab, und der Takt bleibt stehen.Vorgabe true

authorization

object | null

Pflicht bei aktiver Stufe, wenn die Domain keinen Eigentumsnachweis hat und die Organisation eine Agentur ist. Der Zeitplan gibt die Beauftragung an jeden Lauf weiter, den er erzeugt. Um 03:00 kann niemand ein Aktenzeichen eintippen, und ein abgewiesener Zeitplan rückt seinen Termin trotzdem weiter, sodass der Ausfall wie Ruhe aussähe. Der erzeugte Lauf bekommt eine Kopie und keinen Verweis, damit ein später geänderter Zeitplan einen bereits gelaufenen Scan nicht umdeutet.

Wöchentlich montags nachts, mit Datenschutz

curl -X POST https://api.red-check.de/v1/schedules \
-H "Authorization: Bearer rc_live_••••••••" \
-H "Content-Type: application/json" \
-d '{
"domain_id": "3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e",
"cadence": "weekly",
"weekday": 0,
"run_window": "night",
"tier": "passive",
"security": true,
"privacy": true
}'

Takt	Angabe
`daily`	täglich
`weekly`	wöchentlich am `weekday`, `0` ist Montag, `6` Sonntag
`monthly`	monatlich am `day_of_month`, `1` bis `28`
`off`	abgeschaltet, Wochentag und Tag bleiben gespeichert

run_window ist ein Zeitfenster in der Ortszeit der Organisation. Ohne Angabe gilt night. Die Minute darin zieht der Server, damit nicht alle Läufe zugleich starten. Wer eine feste Uhrzeit braucht, sendet stattdessen run_minute, die Minute des Tages in UTC von 0 bis 1439; das Fenster folgt dann dieser Minute. Stehen beide im Körper, gewinnt run_window, beim Ändern allerdings nur, wenn es sich vom gespeicherten Fenster unterscheidet. run_minute in der Antwort steht in UTC.

Ein Zeitplan wird nicht am Kontingent abgewiesen. Passt er nicht mehr in den Monat, speichert die API ihn trotzdem mit state: "waiting_quota". Er startet von selbst, sobald wieder Platz ist.

201

Angelegt.

400

Eingabe ungültig (`validation_failed`).

402

Zeitpläne sind im Plan nicht enthalten (`plan_upgrade_required`). Bei Abrechnung je Lauf (Agentur) kommt außerdem `price_not_set`, wenn der Zeitplan aktiv ist und für eines seiner Pakete kein Preis hinterlegt ist; `details.packages` nennt die Pakete ohne Preis (aus `passive`, `active`, `privacy`, `accessibility`).

403

Domain nicht verifiziert (`domain_not_verified`).

409

Zustand passt nicht (`conflict`, `already_exists`).

Im Plan Free antwortet POST mit 402 plan_upgrade_required. Bei Abrechnung je Lauf kommt 402 price_not_set, wenn für ein Paket des Zeitplans kein Preis vereinbart ist; details.packages nennt die Pakete. Die Preise prüft die API nur beim Speichern eines aktiven Zeitplans, beim Anlegen wie beim Ändern. Einen abgeschalteten Zeitplan (cadence: "off" oder active: false) können Sie auch ohne vereinbarte Preise speichern. Eine aktive Stufe auf einer Domain ohne Eigentumsnachweis ergibt 403 domain_not_verified.

Ändern

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

Der Körper hat dieselben Felder wie beim Anlegen. Zum Abschalten setzen Sie cadence: "off", für eine Pause paused_until mit einem Datum.

Zeitpläne mit automatic: true hat der Plan angelegt, im Plan Pro einen monatlichen passiven Lauf je Domain. Die erste Änderung setzt automatic auf false. Ab dann passt der Server den Zeitplan nicht mehr an den Plan an.

200

Geändert.

400

Eingabe ungültig (`validation_failed`).

402

`privacy` oder `accessibility` im Plan Free (`plan_upgrade_required`, `details.module` mit dem ersten, `details.modules` mit allen gesperrten Bereichen). Bei Abrechnung je Lauf (Agentur) kommt außerdem `price_not_set`, wenn der Zeitplan aktiv ist und für eines seiner Pakete kein Preis hinterlegt ist; `details.packages` nennt die Pakete ohne Preis (aus `passive`, `active`, `privacy`, `accessibility`).

Löschen

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

Ein gelöschter Zeitplan lässt sich im Plan Free nicht neu anlegen. Wer ihn später wieder braucht, schaltet ihn mit cadence: "off" ab.

204

Gelöscht.

400

Eingabe ungültig (`validation_failed`).

Kontingent

GEThttps://api.red-check.de/v1/schedules/kontingent

Geplante Läufe im Monat gegen das, was der Plan trägt, eine Zeile je Stufe. limit: null heißt unbegrenzt, so etwa bei Abrechnung je Lauf. Mit preview_domain_ids und preview_cadence rechnet der Server vorab, was eine Änderung an mehreren Domains hinzufügen würde.

ParameterTypBeschreibung

preview_domain_ids

string

Die Domains der Mehrfachauswahl als Kommaliste (`style: form, explode: false`). Ohne `preview_cadence` hat der Parameter keine Wirkung.

preview_cadence

enum

Der Takt, auf den die Auswahl gestellt werden soll.off · daily · weekly · monthly

FeldTypBeschreibung

plan

enumPflicht

–free · pro · agency

period_end

string (date-time)Pflicht

Ende des laufenden Abrechnungszeitraums.

tiers

object[]Pflicht

–

waiting_schedules

integerPflicht

Zeitpläne über alle Stufen im Zustand `waiting_quota`. Die Zahl hinter dem Hinweis „2 warten auf Kontingent".

packages

object[]

Seit 1.12.0, nur in einem Kundenkonto einer Agentur: die Balken je Paket. Ein Zeitplan braucht für jedes seiner Pakete Platz, sonst wartet er (`waiting_quota`). `planned`, `waiting` und `waiting_schedules` sind hier gefüllt.

Rechte

Aufruf	`read_only`	`start_scans`	`full`
`GET /v1/schedules`, `GET /v1/schedules/kontingent`	ja	ja	ja
`POST`, `PATCH`, `DELETE`	nein	nein	ja

Ein start_scans-Schlüssel startet Läufe, ändert aber keine Zeitpläne. Er bekommt 403 api_key_scope_insufficient.