# API-Dokumentation

## Einstieg

Die Kunden-API von exatics startet Audits, liefert Status und Ergebnis, erzeugt PDF-Berichte und verwaltet Löschungen und Dienst-Freigaben. Sie steht Organisationen zur Verfügung, für die exatics die API freigeschaltet hat.

Den Schlüssel legt der Inhaber der Organisation im Portal unter API-Schlüssel an (/portal/api/). Dort legt er auch die Rechte des Schlüssels und die erlaubten IP-Adressen fest.

## Authentifizierung

Jeder Aufruf sendet den Schlüssel im Header Authorization, auch GET /api/v1 und GET /api/v1/openapi.json:

```
Authorization: Bearer exa_<16 Zeichen>_<43 Zeichen>
```

Format des Schlüssels: exa_, dann 16 Zeichen aus a–z und 0–9, ein Unterstrich und 43 Zeichen aus A–Z, a–z, 0–9, _ und -. Ohne Schlüssel antwortet die API mit 401 key_missing, mit einem ungültigen oder widerrufenen Schlüssel mit 401 key_invalid.

## Anfragen

- Basis-URL: https://www.exatics.de/api/v1
- Anfragekörper sind JSON-Objekte. Antworten sind JSON, außer beim erfolgreichen PDF-Abruf (application/pdf) und bei den Abwehrantworten vor der Schlüsselprüfung (Abschnitt „Fehlerformat“). POST-Aufrufe senden immer den Header Content-Type: application/json und ihre Felder als JSON-Objekt; ohne Felder darf der Körper leer sein. Ein leerer Körper gilt wie {}; invalid_json kommt nur, wenn der Körper weder leer noch ein JSON-Objekt ist.
- Unbekannte Felder werden ohne Fehler ignoriert: bei GET in der Query, bei POST im Körper. Query-Parameter einer POST-Anfrage wertet die API nicht aus.
- POST-Aufrufe brauchen den Header Idempotency-Key: 1–100 Zeichen aus A–Z, a–z, 0–9, _ und -. Eine Wiederholung mit demselben Key startet nichts doppelt; die Regeln stehen im Abschnitt „Idempotenz“.
- GET /api/v1 listet die Endpunkte, die Ihr Schlüssel nutzen darf, mit Pflichtfeldern; GET /api/v1/openapi.json beschreibt alle Endpunkte im Format OpenAPI 3.1.

Beispiel: Audit starten

```
curl -X POST https://www.exatics.de/api/v1/audits \
  -H "Authorization: Bearer <Schlüssel>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: start-0001" \
  -d '{"url": "https://www.example.com/"}'
```

## Grenzwerte

| Grenze | Wert |
| --- | --- |
| Übrige Aufrufe je Schlüssel und Minute | 60 |
| Starts und PDF-Berichte je Schlüssel und Minute (Audit starten, erneut prüfen, PDF-Bericht) | 10 |
| Aktive Schlüssel je Organisation | 20 |
| Größe des Anfragekörpers | 1048576 Byte |
| Gültigkeit eines Idempotency-Key | 24 Stunden |

Beide Grenzen zählen getrennt: Ein Start, eine erneute Prüfung oder ein PDF-Bericht zählt nur zur Grenze der Starts und PDF-Berichte, nicht zu den übrigen Aufrufen.

Über den Grenzen je Schlüssel antwortet die API mit 429 rate_limited und dem Header Retry-After (Sekunden). Zusätzlich begrenzt der Server die Anfragen je IP-Adresse; darüber kommt 429 ohne JSON-Körper und ohne Retry-After. Warten Sie dann kurz und wiederholen Sie die Anfrage.

## Fehlerformat

Fehler kommen als JSON-Objekt mit error (Schlüssel aus dem Fehlerkatalog unten), message und next_step, bei einigen Fehlern zusätzlich details (Tabelle „Fehlerdetails“ im Abschnitt „Fehlerdetails“).

```
{
    "error": "permission_missing",
    "message": "Dem Schlüssel fehlt das nötige Recht.",
    "next_step": "Recht laut details.permission im Portal einem Schlüssel geben.",
    "details": {
        "permission": "audits.start"
    }
}
```

Ohne JSON-Körper antworten die Begrenzung je IP-Adresse (429) sowie die Abwehr gesperrter IP-Adressen und auffälliger Pfade (404 als HTML), weil sie vor der Schlüsselprüfung greifen.

## Ablauf eines Audits

- POST /api/v1/audits mit url startet ein Audit; die Antwort enthält audit {id, status} und reused. Start und erneute Prüfung antworten mit 200, wenn audit.status completed ist, sonst mit 202; reused true heißt, dass das Audit schon bestand.
- GET /api/v1/audits/{id} meldet den Status: queued, running, completed, failed.
- Bei completed enthält dieselbe Antwort das Ergebnis (Abschnitt „Ergebnis eines Audits“); GET /api/v1/audits/{id}/pdf liefert den PDF-Bericht.

## Idempotenz

- Ein Idempotency-Key gilt je API-Schlüssel.
- Die gespeicherte Antwort gehört zu Methode, Pfad und Körper: Derselbe Key mit anderem Körper oder an einem anderen Endpunkt ergibt 409 idempotency_conflict.
- Die Frist von 24 Stunden läuft ab der ersten Anfrage mit dem Key; danach wird eine Anfrage mit demselben Key neu ausgeführt.
- Solange die erste Anfrage läuft, ergibt jede weitere mit demselben Key 409 idempotency_in_progress, höchstens 300 Sekunden lang.
- Gespeichert werden Erfolgsantworten und die Fehler start_denied, audit_rejected, audit_hidden, device_not_allowed; bei jedem anderen Fehler ist der Key wieder frei.
- Eine Wiederholung liefert HTTP-Status und Körper der gespeicherten Antwort; audit.status darin ist der Stand der ersten Antwort, den aktuellen Stand liefert GET /api/v1/audits/{id}.
- Endet die erste Anfrage mit einem nicht gespeicherten Fehler oder einem Serverfehler, führt eine Wiederholung die Anfrage erneut aus; ein dabei schon angelegtes Audit derselben URL kommt dann als bestehendes Audit (reused true).
- Ausführung und Speicherung der Antwort sind nicht atomar: Bricht eine Anfrage nach einer Änderung ab (Serverfehler oder Verbindungsabbruch), kann die Änderung schon wirksam sein. Prüfen Sie vor einer Wiederholung den Zustand: Löschungen und Reaktivierungen mit GET /api/v1/deletions, Audits mit GET /api/v1/audits. Bei Freigaben endet eine Wiederholung einer schon wirksamen Änderung mit 422 approval_rejected; details.reason nennt den Grund.
- Fehler aus der Prüfung vor dem Aufruf (permission_missing, missing_field, invalid_parameter) belegen den Key nicht.
- reused in der Antwort beschreibt das Audit, nicht die Wiederholung der Anfrage.

## Fehlerdetails

| Fehler | Feld in details | Typ |
| --- | --- | --- |
| permission_missing | permission | Text (Code des Rechts) |
| rate_limited | retry_after_s | Ganzzahl (Sekunden) |
| missing_field | missing | Liste von Feldnamen |
| missing_field | schema | Objekt (Eingaben des Endpunkts) |
| invalid_parameter | parameter | Text (Feldname) |
| start_denied, audit_rejected, approval_rejected | reason | Text (Grund in Klartext) |

Bei allen anderen Fehlern fehlt details.

Kein Endpunkt steht nur Inhabern offen (Spalte „Nur Inhaber“: ja); owner_required tritt in v1 nicht auf.

## Endpunkte

| Methode | Pfad | Recht | Nur Inhaber | Starts und PDF | Beschreibung | Ausgabe |
| --- | --- | --- | --- | --- | --- | --- |
| GET | /api/v1 | – | nein | nein | Für diesen Schlüssel nutzbare Endpunkte mit Pflichtfeldern | version, endpoints |
| GET | /api/v1/openapi.json | – | nein | nein | Beschreibung aller Endpunkte im Format OpenAPI 3.1 | OpenAPI-Dokument |
| GET | /api/v1/me | – | nein | nein | Schlüssel, Organisation, Rolle, Rechte und Zugangsquelle | key, organization, role, permissions, access |
| POST | /api/v1/audits | audits.start | nein | ja | Audit einer URL starten (Idempotency-Key Pflicht) | audit {id, status}, reused |
| POST | /api/v1/audits/{id}/recheck | audits.start | nein | ja | Audit erneut prüfen (Idempotency-Key Pflicht) | audit {id, status}, reused |
| GET | /api/v1/audits | audits.read | nein | nein | Audits der Organisation, neueste zuerst | items, page, per_page, total |
| GET | /api/v1/audits/{id} | audits.read | nein | nein | Status und Ergebnis eines Audits | Ergebnisvertrag (Doku) |
| GET | /api/v1/audits/{id}/pdf | audits.pdf | nein | ja | PDF-Bericht eines Audits (Datenschutz oder Website-Health) | application/pdf |
| POST | /api/v1/deletions | audits.manage | nein | nein | Löschung der Audits einer URL vormerken, wirksam zum 1. des Folgemonats (Idempotency-Key Pflicht) | deletion {id, url, effective_from} |
| GET | /api/v1/deletions | audits.manage | nein | nein | Offene Löschungen einzelner URLs, im laufenden Monat rückgängig zu machen | items [{id, url, deleted_at, effective_from}] |
| POST | /api/v1/deletions/{id}/reactivate | audits.manage | nein | nein | Offene Löschung einer URL rückgängig machen (Idempotency-Key Pflicht) | deletion {id, reactivated} |
| POST | /api/v1/audits/{id}/approvals | approvals.write | bedingt | nein | Dienst im Audit freigeben oder Freigabe aufheben (Idempotency-Key Pflicht); level und slug der Antwort sind die Eingabewerte | approval {action, level, slug} |
| GET | /api/v1/services | audits.read | nein | nein | Kurzbeschreibung und Einstufung eines Dienstes aus dem Audit-Ergebnis | service {slug, name, category, provider_country, is_eu, description, service_type} |

Spalte „Starts und PDF“, Wert „ja“: Der Aufruf zählt zu den Starts und PDF-Berichten je Minute (Abschnitt „Grenzwerte“).

Spalte „Nur Inhaber“, Wert „bedingt“: Nur einzelne Eingaben verlangen den Schlüssel eines Inhabers (bei POST /api/v1/audits/{id}/approvals level organization). Mit dem Schlüssel eines Mitglieds antwortet der Endpunkt dann mit 422 approval_rejected (details.reason).

## Rechte

| Recht | Bezeichnung | Beschreibung | Endpunkte |
| --- | --- | --- | --- |
| approvals.write | Dienste freigeben | Dienste in einem Audit als freigegeben einstufen, Freigaben aufheben und ihre Darstellung wählen. Nur in Bezahltarifen. | POST /api/v1/audits/{id}/approvals |
| audits.manage | Audits löschen | Löschung von Audits einer URL vormerken (wirksam zum 1. des Folgemonats), offene Löschungen abrufen und im laufenden Monat rückgängig machen. | POST /api/v1/deletions, GET /api/v1/deletions, POST /api/v1/deletions/{id}/reactivate |
| audits.pdf | PDF-Berichte herunterladen | Den PDF-Bericht eines Audits abrufen, sofern der Tarif PDF-Export enthält. | GET /api/v1/audits/{id}/pdf |
| audits.read | Audits lesen | Audits auflisten, Status abfragen und Ergebnisse mit Scores, Befunden und Dienstinfos abrufen. | GET /api/v1/audits, GET /api/v1/audits/{id}, GET /api/v1/services |
| audits.start | Audits starten | Audits für einzelne URLs starten und erneut prüfen. Verbraucht das monatliche Audit-Kontingent. | POST /api/v1/audits, POST /api/v1/audits/{id}/recheck |

## Fehlerkatalog

| Schlüssel | HTTP-Status | Meldung | Nächster Schritt | Endpunkte |
| --- | --- | --- | --- | --- |
| key_missing | 401 | Kein API-Schlüssel übergeben. | Header Authorization: Bearer <Schlüssel> mitsenden. | alle |
| key_invalid | 401 | Der API-Schlüssel ist ungültig oder widerrufen. | Schlüssel im Portal unter API-Schlüssel prüfen oder neu anlegen (Inhaber der Organisation). | alle |
| ip_not_allowed | 403 | Aufrufe von dieser IP-Adresse sind für den Schlüssel nicht freigegeben. | IP-Freigabeliste des Schlüssels im Portal prüfen. | alle |
| access_organization_unknown | 403 | Die Organisation des Schlüssels ist unbekannt. | Support kontaktieren. | alle |
| access_organization_inactive | 403 | Die Organisation ist deaktiviert. | Support kontaktieren. | alle |
| access_payment_overdue | 403 | Die API ist wegen einer offenen Zahlung gesperrt. | Offene Zahlung im Portal unter /portal/billing begleichen. | alle |
| access_not_enabled | 403 | Die API ist für diese Organisation nicht freigeschaltet. | Support kontaktieren. | alle |
| rate_limited | 429 | Zu viele Aufrufe in kurzer Zeit. | Nach der in Retry-After genannten Zahl Sekunden erneut versuchen. | alle |
| method_not_allowed | 405 | Diese HTTP-Methode ist hier nicht erlaubt. | Eine Methode aus dem Header Allow verwenden. | alle |
| unsupported_media_type | 415 | Der Anfragekörper muss JSON sein. | Header Content-Type: application/json setzen. | alle |
| payload_too_large | 413 | Der Anfragekörper ist zu groß. | Körper verkleinern. | alle |
| invalid_json | 400 | Der Anfragekörper ist kein gültiges JSON-Objekt. | Ein JSON-Objekt senden. | alle |
| missing_field | 400 | Ein Pflichtfeld fehlt. | Felder laut details.schema ergänzen. | alle |
| unknown_endpoint | 404 | Diesen Endpunkt gibt es nicht. | Verfügbare Endpunkte unter GET /api/v1 abrufen. | alle |
| unknown_version | 404 | Diese API-Version gibt es nicht. | Version v1 verwenden: /api/v1. | alle |
| permission_missing | 403 | Dem Schlüssel fehlt das nötige Recht. | Recht laut details.permission im Portal einem Schlüssel geben. | alle |
| owner_required | 403 | Diese Funktion steht nur dem Inhaber der Organisation zu. | Schlüssel eines Inhabers verwenden. | reserviert, in v1 nicht verwendet |
| invalid_parameter | 400 | Ein Feld hat einen ungültigen Typ oder Wert. | Feld laut details.parameter und der Beschreibung unter GET /api/v1 korrigieren. | alle |
| idempotency_key_missing | 400 | Der Header Idempotency-Key fehlt. | Bei POST einen eindeutigen Idempotency-Key mitsenden (1–100 Zeichen A–Z, a–z, 0–9, _ und -). | alle POST |
| idempotency_key_invalid | 400 | Der Idempotency-Key hat ein ungültiges Format. | 1–100 Zeichen aus A–Z, a–z, 0–9, _ und - verwenden. | alle POST |
| idempotency_conflict | 409 | Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet (anderer Körper, andere Methode oder anderer Pfad). | Für eine neue Anfrage einen neuen Idempotency-Key wählen. | alle POST |
| idempotency_in_progress | 409 | Eine Anfrage mit diesem Idempotency-Key läuft noch. | Kurz warten und dieselbe Anfrage wiederholen. | alle POST |
| maintenance | 503 | exatics wird gerade gewartet. | Später erneut versuchen. | alle |
| internal_error | 500 | Interner Fehler. | Später erneut versuchen, bei Wiederholung Support kontaktieren. | alle |
| unknown_audit | 404 | Dieses Audit gibt es nicht. | Id aus GET /api/v1/audits verwenden. | POST /api/v1/audits/{id}/recheck, GET /api/v1/audits/{id}, GET /api/v1/audits/{id}/pdf, POST /api/v1/audits/{id}/approvals |
| start_denied | 403 | Das Audit kann derzeit nicht gestartet werden. | Grund laut details.reason beheben, etwa Kontingent, Domain-Freigabe im Portal oder eine vorgemerkte URL-Löschung (GET /api/v1/deletions, POST /api/v1/deletions/{id}/reactivate); die Löschung einer ganzen Domain im Portal bei den Domains. | POST /api/v1/audits, POST /api/v1/audits/{id}/recheck |
| audit_rejected | 422 | Diese URL kann nicht geprüft werden. | Grund laut details.reason prüfen und eine andere URL verwenden. | POST /api/v1/audits, POST /api/v1/audits/{id}/recheck |
| audit_hidden | 409 | Das passende Audit ist in Ihrer Organisation nicht abrufbar, etwa weil es gelöscht wurde. | Support kontaktieren, wenn für diese URL ein neues Audit nötig ist. | POST /api/v1/audits, POST /api/v1/audits/{id}/recheck |
| device_not_allowed | 422 | Der Gerätetyp desktop ist in diesem Tarif nicht enthalten. | device weglassen oder mobile verwenden. | POST /api/v1/audits |
| audit_not_completed | 409 | Das Audit ist noch nicht abgeschlossen. | Warten, bis GET /api/v1/audits/{id} den Status completed meldet, dann erneut senden. | GET /api/v1/audits/{id}/pdf, POST /api/v1/audits/{id}/approvals |
| approval_rejected | 422 | Die Freigabe wurde abgelehnt. | Grund laut details.reason beheben. | POST /api/v1/audits/{id}/approvals |
| unknown_url | 404 | Diese URL wurde in Ihrer Organisation nicht geprüft. | Die URL genau so angeben, wie sie in GET /api/v1/audits steht. | POST /api/v1/deletions |
| deletion_already_scheduled | 409 | Für diese URL oder ihre ganze Domain ist bereits eine Löschung vorgemerkt, oder die Vormerkung wird gerade bearbeitet. | Offene URL-Löschungen mit GET /api/v1/deletions abrufen; die Löschung einer ganzen Domain steht im Portal bei den Domains. | POST /api/v1/deletions |
| not_reactivatable | 409 | Diese Löschung lässt sich nicht rückgängig machen. | Nur offene URL-Löschungen aus GET /api/v1/deletions lassen sich bis zum Monatsende rückgängig machen; Löschungen ganzer Domains im Portal. | POST /api/v1/deletions/{id}/reactivate |
| unknown_service | 404 | Diesen Dienst gibt es nicht. | slug aus dem Audit-Ergebnis (GET /api/v1/audits/{id}) verwenden. | GET /api/v1/services |
| pdf_not_in_plan | 403 | Der PDF-Bericht ist in diesem Tarif nicht enthalten. | Tarif mit PDF-Bericht buchen. | GET /api/v1/audits/{id}/pdf |
| audit_expired | 410 | Die Detaildaten dieses Audits sind abgelaufen. | Ein neues Audit starten (POST /api/v1/audits). | GET /api/v1/audits/{id}/pdf |
| pdf_failed | 502 | Der PDF-Bericht konnte nicht erzeugt werden. | Später erneut versuchen, bei Wiederholung Support kontaktieren. | GET /api/v1/audits/{id}/pdf |

Spalte „Endpunkte“, Wert „alle“: nicht an einen Endpunkt gebunden; der Fehler tritt auf, wo seine Voraussetzung besteht (z. B. Körper bei POST, Pflichtfelder bei Endpunkten mit Eingaben).

## Eingaben je Endpunkt

### GET /api/v1

Keine Eingaben.

### GET /api/v1/openapi.json

Keine Eingaben.

### GET /api/v1/me

Keine Eingaben.

### POST /api/v1/audits

| Name | Ort | Typ | Pflicht | Werte |
| --- | --- | --- | --- | --- |
| Idempotency-Key | Header | string | ja | Muster ^[A-Za-z0-9_-]{1,100}$ |
| url | Körper | string | ja | – |
| device | Körper | string | nein | mobile, desktop |
| focus | Körper | string | nein | privacy, health |

- device ohne Angabe: mobile; desktop nur im Bezahltarif, sonst 422 device_not_allowed.
- focus ohne Angabe: privacy (Ansicht „Datenschutz & Consent“).
- focus wählt die Ansicht des Audits im Portal; das JSON-Ergebnis ändert er nicht. Der PDF-Bericht richtet sich nur nach dem focus des PDF-Abrufs.
- reused false: neues Audit; reused true: ein laufendes Audit derselben URL (je nach Eingabe zählen auch die Schreibweise mit oder ohne www. bei Hauptdomains und mit oder ohne abschließenden Schrägstrich dazu) oder ein abgeschlossenes, höchstens 28 Tage nach Abschluss der Prüfung (der Zeitraum kann sich ändern). Läuft dessen Auswertung noch, ist audit.status running und die Antwort 202. Für ein neues Audit POST /api/v1/audits/{id}/recheck nutzen.
- Ist das über die URL gefundene Audit in Ihrer Organisation nicht abrufbar, kommt 409 audit_hidden.

### POST /api/v1/audits/{id}/recheck

| Name | Ort | Typ | Pflicht | Werte |
| --- | --- | --- | --- | --- |
| id | Pfad | string | ja | – |
| Idempotency-Key | Header | string | ja | Muster ^[A-Za-z0-9_-]{1,100}$ |
| – | Körper | object | nein | keine Felder; leerer Körper oder {} (Content-Type: application/json ist trotzdem nötig) |

- Antwort: neues Audit mit neuer id (reused false) oder das laufende Audit derselben URL (reused true); HTTP-Status nach der Regel im Abschnitt „Ablauf eines Audits“.
- Ist die übergebene id nicht abrufbar, kommt 404 unknown_audit; ist das über die URL gefundene laufende oder das neu angelegte Audit nicht abrufbar, 409 audit_hidden.
- Das neue Audit übernimmt den focus des ursprünglichen Audits nicht; das Portal zeigt es in der Ansicht, die der Betrachter gewählt hat (Adresse oder Sitzung), sonst „Datenschutz & Consent“.

### GET /api/v1/audits

| Name | Ort | Typ | Pflicht | Werte |
| --- | --- | --- | --- | --- |
| page | Query | integer | nein | 1–100000 |
| per_page | Query | integer | nein | 1–100 |
| domain | Query | string | nein | – |
| status | Query | string | nein | queued, running, completed, failed |
| since | Query | string (date) | nein | – |

- page ohne Angabe 1, per_page ohne Angabe 25.
- since: Datum, einschließlich ab 00:00 Uhr deutscher Zeit (Europe/Berlin), bezogen auf den Start des Audits.
- domain: exakter Vergleich mit dem Feld domain der Audits. Das Feld enthält in der Regel die Hauptdomain (z. B. example.com), auch für Audits von www.example.com und anderen Subdomains; den Filterwert aus dem Feld domain eines früheren Ergebnisses übernehmen. Groß- und Kleinschreibung sowie Umlaute und Akzente werden beim Vergleich nicht unterschieden; ein Punkt am Ende und die Punycode-Schreibweise internationaler Domains werden nicht angeglichen.
- Sortierung: nach Abschluss, ohne Abschluss nach Start, neueste zuerst; bei gleicher Zeit das später angelegte Audit zuerst.
- total wird bei jedem Aufruf neu gezählt. Die Seiten entstehen aus page und per_page; kommt zwischen zwei Abrufen ein Audit hinzu oder schließt eines ab, können Einträge doppelt erscheinen oder fehlen.

### GET /api/v1/audits/{id}

| Name | Ort | Typ | Pflicht | Werte |
| --- | --- | --- | --- | --- |
| id | Pfad | string | ja | – |

- Für nicht vorhandene, fremde, ausgeblendete und gelöschte Audits antworten alle Endpunkte unter /api/v1/audits/{id} gleich mit 404 unknown_audit.

### GET /api/v1/audits/{id}/pdf

| Name | Ort | Typ | Pflicht | Werte |
| --- | --- | --- | --- | --- |
| id | Pfad | string | ja | – |
| focus | Query | string | nein | privacy, health |

- focus ohne Angabe: Bericht „Datenschutz & Consent“.
- Jeder Abruf erzeugt den Bericht neu und zählt zu den Starts und PDF-Berichten je Minute.
- Je Organisation entsteht ein Bericht zur Zeit; ein gleichzeitiger zweiter Abruf erhält 429 rate_limited mit Retry-After und details.retry_after_s. Diese Sperre gilt je Organisation, unabhängig von den Grenzen je Schlüssel.

### POST /api/v1/deletions

| Name | Ort | Typ | Pflicht | Werte |
| --- | --- | --- | --- | --- |
| Idempotency-Key | Header | string | ja | Muster ^[A-Za-z0-9_-]{1,100}$ |
| url | Körper | string | ja | – |

### GET /api/v1/deletions

Keine Eingaben.

- deleted_at: Zeitpunkt der Vormerkung (ISO 8601 mit Zeitzonen-Offset).
- effective_from: Datum ohne Uhrzeit, ab dem die Löschung wirkt; bis dahin lässt sie sich mit POST /api/v1/deletions/{id}/reactivate rückgängig machen.

### POST /api/v1/deletions/{id}/reactivate

| Name | Ort | Typ | Pflicht | Werte |
| --- | --- | --- | --- | --- |
| id | Pfad | string | ja | – |
| Idempotency-Key | Header | string | ja | Muster ^[A-Za-z0-9_-]{1,100}$ |
| – | Körper | object | nein | keine Felder; leerer Körper oder {} (Content-Type: application/json ist trotzdem nötig) |

### POST /api/v1/audits/{id}/approvals

| Name | Ort | Typ | Pflicht | Werte |
| --- | --- | --- | --- | --- |
| id | Pfad | string | ja | – |
| Idempotency-Key | Header | string | ja | Muster ^[A-Za-z0-9_-]{1,100}$ |
| action | Körper | string | ja | approve, revoke |
| level | Körper | string | ja | organization, project |
| slug | Körper | string | ja | – |
| reason | Körper | string | nein | – |

- Nur im Bezahltarif.
- level organization nur mit dem Schlüssel eines Inhabers der Organisation (Rolle des Benutzers, der den Schlüssel angelegt hat); mit dem Schlüssel eines Mitglieds 422 approval_rejected.
- level project wirkt auf das Projekt der Domain des Audits; ohne Projekt wird die Anfrage abgelehnt.
- reason: höchstens 500 Zeichen, nur bei approve gespeichert, nicht in der Antwort enthalten.
- Abgelehnt wird außerdem, wenn der Dienst im Audit nicht vorkommt oder nicht freigabefähig ist, wenn er bereits freigegeben ist bzw. beim Widerruf keine Freigabe besteht und wenn das Projekt nicht verfügbar ist.
- Jede Ablehnung kommt als 422 approval_rejected mit details.reason.

### GET /api/v1/services

| Name | Ort | Typ | Pflicht | Werte |
| --- | --- | --- | --- | --- |
| slug | Query | string | ja | – |

- slug wie im Audit-Ergebnis (technologies) oder als Kurzform (Teil nach dem letzten „/“).
- Der Aufruf braucht kein Audit, er liest aus dem allgemeinen Dienstverzeichnis; ein unbekannter slug ergibt 404 unknown_service.

## Ergebnis eines Audits

GET /api/v1/audits/{id} liefert immer denselben Satz von Feldern. Solange status nicht completed ist, sind alle Felder ab analyzed_at null. Bei failed nennt die API keinen Grund. Ein neuer Versuch geht über POST /api/v1/audits/{id}/recheck; scheitert auch er, hilft der Support. Zeiten stehen im Format ISO 8601 mit Zeitzonen-Offset.

| Feld | Inhalt |
| --- | --- |
| id | Kennung des Audits für alle weiteren Aufrufe |
| url | geprüfte URL |
| domain | Domain der URL |
| status | queued, running, completed oder failed |
| device | Gerätetyp der Prüfung (mobile oder desktop) |
| created_at | Zeitpunkt des Starts (ISO 8601 mit Zeitzonen-Offset) |
| completed_at | Zeitpunkt des Abschlusses der Prüfung, bei failed des Abbruchs. null, solange der Abruf der Seiten noch läuft (queued oder running); bei running kann er schon gesetzt sein, wenn nur die Auswertung noch läuft; bei failed kann er fehlen. |
| analyzed_at | Zeitpunkt der Auswertung |
| stale | true, wenn das Ergebnis als veraltet gilt |
| language | erkannte Sprache der Seite |
| hosting_country | Land des Hostings |
| health | Website-Health: {score, traffic_light} |
| scores | je sichtbarem Prüfbereich {score, traffic_light, neutral} |
| issues | Befunde: Liste {type, label, description} |
| technologies | erkannte Dienste: Liste {slug, category, phase, consent_class, hosting_type} |
| cookies | Cookies: Liste {name, domain, category, party, phase, expiry, secure} |
| cookie_count | Anzahl der Cookies oder null |
| cmp | Consent-Banner: {detected, name, properly_configured, blocks_effectively} oder null |
| legal_pages | Rechtstexte: Liste {found, url} |

Im Tarif Free sind die Zahlenwerte (score), die Beschreibung der Befunde, phase der Technologien sowie properly_configured und blocks_effectively des Consent-Banners null. Je nach Tarif sind die Listen der Befunde und Cookies gekürzt oder leer, die Liste der Technologien leer; ohne Zugang zu den Cookies ist cookie_count null.
