API-Dokumentation

Diese Seite als Markdown für KI-Werkzeuge: /doku/api.md

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

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

Grenzwerte
Übrige Aufrufe je Schlüssel und Minute60
Starts und PDF-Berichte je Schlüssel und Minute (Audit starten, erneut prüfen, PDF-Bericht)10
Aktive Schlüssel je Organisation20
Größe des Anfragekörpers1048576 Byte
Gültigkeit eines Idempotency-Key24 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

Idempotenz

Fehlerdetails

FehlerFeld in detailsTyp
permission_missingpermissionText (Code des Rechts)
rate_limitedretry_after_sGanzzahl (Sekunden)
missing_fieldmissingListe von Feldnamen
missing_fieldschemaObjekt (Eingaben des Endpunkts)
invalid_parameterparameterText (Feldname)
start_denied, audit_rejected, approval_rejectedreasonText (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

MethodePfadRechtNur InhaberStarts und PDFBeschreibungAusgabe
GET/api/v1–neinneinFür diesen Schlüssel nutzbare Endpunkte mit Pflichtfeldernversion, endpoints
GET/api/v1/openapi.json–neinneinBeschreibung aller Endpunkte im Format OpenAPI 3.1OpenAPI-Dokument
GET/api/v1/me–neinneinSchlüssel, Organisation, Rolle, Rechte und Zugangsquellekey, organization, role, permissions, access
POST/api/v1/auditsaudits.startneinjaAudit einer URL starten (Idempotency-Key Pflicht)audit {id, status}, reused
POST/api/v1/audits/{id}/recheckaudits.startneinjaAudit erneut prüfen (Idempotency-Key Pflicht)audit {id, status}, reused
GET/api/v1/auditsaudits.readneinneinAudits der Organisation, neueste zuerstitems, page, per_page, total
GET/api/v1/audits/{id}audits.readneinneinStatus und Ergebnis eines AuditsErgebnisvertrag (Doku)
GET/api/v1/audits/{id}/pdfaudits.pdfneinjaPDF-Bericht eines Audits (Datenschutz oder Website-Health)application/pdf
POST/api/v1/deletionsaudits.manageneinneinLöschung der Audits einer URL vormerken, wirksam zum 1. des Folgemonats (Idempotency-Key Pflicht)deletion {id, url, effective_from}
GET/api/v1/deletionsaudits.manageneinneinOffene Löschungen einzelner URLs, im laufenden Monat rückgängig zu machenitems [{id, url, deleted_at, effective_from}]
POST/api/v1/deletions/{id}/reactivateaudits.manageneinneinOffene Löschung einer URL rückgängig machen (Idempotency-Key Pflicht)deletion {id, reactivated}
POST/api/v1/audits/{id}/approvalsapprovals.writebedingtneinDienst im Audit freigeben oder Freigabe aufheben (Idempotency-Key Pflicht); level und slug der Antwort sind die Eingabewerteapproval {action, level, slug}
GET/api/v1/servicesaudits.readneinneinKurzbeschreibung und Einstufung eines Dienstes aus dem Audit-Ergebnisservice {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

RechtBezeichnungBeschreibungEndpunkte
approvals.writeDienste freigebenDienste in einem Audit als freigegeben einstufen, Freigaben aufheben und ihre Darstellung wählen. Nur in Bezahltarifen.POST /api/v1/audits/{id}/approvals
audits.manageAudits löschenLö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.pdfPDF-Berichte herunterladenDen PDF-Bericht eines Audits abrufen, sofern der Tarif PDF-Export enthält.GET /api/v1/audits/{id}/pdf
audits.readAudits lesenAudits 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.startAudits startenAudits 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üsselHTTP-StatusMeldungNächster SchrittEndpunkte
key_missing401Kein API-Schlüssel übergeben.Header Authorization: Bearer <Schlüssel> mitsenden.alle
key_invalid401Der 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_allowed403Aufrufe von dieser IP-Adresse sind für den Schlüssel nicht freigegeben.IP-Freigabeliste des Schlüssels im Portal prüfen.alle
access_organization_unknown403Die Organisation des Schlüssels ist unbekannt.Support kontaktieren.alle
access_organization_inactive403Die Organisation ist deaktiviert.Support kontaktieren.alle
access_payment_overdue403Die API ist wegen einer offenen Zahlung gesperrt.Offene Zahlung im Portal unter /portal/billing begleichen.alle
access_not_enabled403Die API ist für diese Organisation nicht freigeschaltet.Support kontaktieren.alle
rate_limited429Zu viele Aufrufe in kurzer Zeit.Nach der in Retry-After genannten Zahl Sekunden erneut versuchen.alle
method_not_allowed405Diese HTTP-Methode ist hier nicht erlaubt.Eine Methode aus dem Header Allow verwenden.alle
unsupported_media_type415Der Anfragekörper muss JSON sein.Header Content-Type: application/json setzen.alle
payload_too_large413Der Anfragekörper ist zu groß.Körper verkleinern.alle
invalid_json400Der Anfragekörper ist kein gültiges JSON-Objekt.Ein JSON-Objekt senden.alle
missing_field400Ein Pflichtfeld fehlt.Felder laut details.schema ergänzen.alle
unknown_endpoint404Diesen Endpunkt gibt es nicht.Verfügbare Endpunkte unter GET /api/v1 abrufen.alle
unknown_version404Diese API-Version gibt es nicht.Version v1 verwenden: /api/v1.alle
permission_missing403Dem Schlüssel fehlt das nötige Recht.Recht laut details.permission im Portal einem Schlüssel geben.alle
owner_required403Diese Funktion steht nur dem Inhaber der Organisation zu.Schlüssel eines Inhabers verwenden.reserviert, in v1 nicht verwendet
invalid_parameter400Ein Feld hat einen ungültigen Typ oder Wert.Feld laut details.parameter und der Beschreibung unter GET /api/v1 korrigieren.alle
idempotency_key_missing400Der 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_invalid400Der Idempotency-Key hat ein ungültiges Format.1–100 Zeichen aus A–Z, a–z, 0–9, _ und - verwenden.alle POST
idempotency_conflict409Dieser 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_progress409Eine Anfrage mit diesem Idempotency-Key läuft noch.Kurz warten und dieselbe Anfrage wiederholen.alle POST
maintenance503exatics wird gerade gewartet.Später erneut versuchen.alle
internal_error500Interner Fehler.Später erneut versuchen, bei Wiederholung Support kontaktieren.alle
unknown_audit404Dieses 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_denied403Das 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_rejected422Diese 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_hidden409Das 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_allowed422Der Gerätetyp desktop ist in diesem Tarif nicht enthalten.device weglassen oder mobile verwenden.POST /api/v1/audits
audit_not_completed409Das 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_rejected422Die Freigabe wurde abgelehnt.Grund laut details.reason beheben.POST /api/v1/audits/{id}/approvals
unknown_url404Diese 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_scheduled409Fü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_reactivatable409Diese 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_service404Diesen Dienst gibt es nicht.slug aus dem Audit-Ergebnis (GET /api/v1/audits/{id}) verwenden.GET /api/v1/services
pdf_not_in_plan403Der PDF-Bericht ist in diesem Tarif nicht enthalten.Tarif mit PDF-Bericht buchen.GET /api/v1/audits/{id}/pdf
audit_expired410Die Detaildaten dieses Audits sind abgelaufen.Ein neues Audit starten (POST /api/v1/audits).GET /api/v1/audits/{id}/pdf
pdf_failed502Der 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

NameOrtTypPflichtWerte
Idempotency-KeyHeaderstringjaMuster ^[A-Za-z0-9_-]{1,100}$
urlKörperstringja–
deviceKörperstringneinmobile, desktop
focusKörperstringneinprivacy, health

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

NameOrtTypPflichtWerte
idPfadstringja–
Idempotency-KeyHeaderstringjaMuster ^[A-Za-z0-9_-]{1,100}$
–Körperobjectneinkeine Felder; leerer Körper oder {} (Content-Type: application/json ist trotzdem nötig)

GET /api/v1/audits

NameOrtTypPflichtWerte
pageQueryintegernein1–100000
per_pageQueryintegernein1–100
domainQuerystringnein–
statusQuerystringneinqueued, running, completed, failed
sinceQuerystring (date)nein–

GET /api/v1/audits/{id}

NameOrtTypPflichtWerte
idPfadstringja–

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

NameOrtTypPflichtWerte
idPfadstringja–
focusQuerystringneinprivacy, health

POST /api/v1/deletions

NameOrtTypPflichtWerte
Idempotency-KeyHeaderstringjaMuster ^[A-Za-z0-9_-]{1,100}$
urlKörperstringja–

GET /api/v1/deletions

Keine Eingaben.

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

NameOrtTypPflichtWerte
idPfadstringja–
Idempotency-KeyHeaderstringjaMuster ^[A-Za-z0-9_-]{1,100}$
–Körperobjectneinkeine Felder; leerer Körper oder {} (Content-Type: application/json ist trotzdem nötig)

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

NameOrtTypPflichtWerte
idPfadstringja–
Idempotency-KeyHeaderstringjaMuster ^[A-Za-z0-9_-]{1,100}$
actionKörperstringjaapprove, revoke
levelKörperstringjaorganization, project
slugKörperstringja–
reasonKörperstringnein–

GET /api/v1/services

NameOrtTypPflichtWerte
slugQuerystringja–

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.

Felder des Ergebnisses
idKennung des Audits für alle weiteren Aufrufe
urlgeprüfte URL
domainDomain der URL
statusqueued, running, completed oder failed
deviceGerätetyp der Prüfung (mobile oder desktop)
created_atZeitpunkt des Starts (ISO 8601 mit Zeitzonen-Offset)
completed_atZeitpunkt 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_atZeitpunkt der Auswertung
staletrue, wenn das Ergebnis als veraltet gilt
languageerkannte Sprache der Seite
hosting_countryLand des Hostings
healthWebsite-Health: {score, traffic_light}
scoresje sichtbarem Prüfbereich {score, traffic_light, neutral}
issuesBefunde: Liste {type, label, description}
technologieserkannte Dienste: Liste {slug, category, phase, consent_class, hosting_type}
cookiesCookies: Liste {name, domain, category, party, phase, expiry, secure}
cookie_countAnzahl der Cookies oder null
cmpConsent-Banner: {detected, name, properly_configured, blocks_effectively} oder null
legal_pagesRechtstexte: 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.