API¶

verAIficATor stellt seine öffentlichen Daten zusätzlich zur HTML-Seite maschinenlesbar unter /api/v1/ bereit. Alle Pfade in dieser Seite sind relativ zur Basis-URL der jeweiligen Umgebung (https://www.veraificator.com/api/v1/… im Pilotbetrieb).

Eine interaktive, automatisch generierte Referenz mit allen Endpunkten, Parametern und Antwortschemata steht unter GET /api/v1/docs zur Verfügung. Diese Seite hier beschreibt dieselben Endpunkte in Prosa, mit Fokus darauf, was die Daten bedeuten und welche Garantien dahinterstehen — nicht nur ihre Feldnamen.

Drei Vertrauensstufen¶

Bereich	Authentifizierung	Inhalt
Öffentlich (`/api/v1/…`)	keine	ausschließlich aus veröffentlichten Snapshots sowie anonymisierten, plattformweiten Kennzahlen
Institutionell (`/api/v1/institutions/{slug}/…`)	angemeldete Sitzung, mandantengeprüft	private Registerdaten der eigenen Institution — siehe Einsatz in Institutionen
Administration (`/api/v1/admin/…`)	angemeldete Sitzung, Plattform-Administration	zusätzliche Betriebskennzahlen, weiterhin ohne Aufschlüsselung nach Person oder Institution

Alles unter „Öffentlich" ist bewusst so gebaut, dass es ausschließlich aus RecordVersion.snapshot und daraus abgeleiteten, ebenfalls veröffentlichungspflichtigen Zusammenfassungen gespeist wird — derselbe Baustein, der auch die HTML-Seite und das PDF rendert (siehe Grundsätze). Es gibt keinen Pfad, über den ein privates Feld eines institutionellen Registereintrags in eine öffentliche API-Antwort gelangen könnte, weil dieser Teil der API die entsprechenden Datenmodelle gar nicht importiert.

Öffentliche Endpunkte¶

GET /api/v1/records/{id}¶

Der vollständige, maschinenlesbare Record. Für einen Record mit veröffentlichter Version enthält die Antwort den kompletten Snapshot plus drei zusätzliche Felder:

recordHash — die SHA-256-Prüfsumme genau dieses Snapshots (siehe Versionierung); bewusst neben, nicht innerhalb des Snapshots geführt;
versions — die Liste aller veröffentlichten Versionen dieses Records, älteste zuerst (siehe unten);
url — die kanonische, absolute Adresse der Record-Seite.

Ob ein Record das Verifiziert-Kennzeichen trägt, ist nicht Teil der API-Antwort (und nicht des Snapshots): Diese Tatsache erscheint ausschließlich auf der HTML-Seite des Records. Wer bestätigt hat, wird nirgends ausgegeben.

Ein Record, dessen Status zwar bereits öffentlich ist (self_declared oder pending_full_disclosure), der aber noch keine veröffentlichte Version besitzt, liefert stattdessen eine kurze Platzhalter-Antwort:

{
  "recordId": "PILOT-2026-0001",
  "status": "pending_full_disclosure",
  "schemaVersion": "0.3",
  "message": "Full disclosure record is currently being completed."
}

Dieser eine Satz ist bewusst der einzige englische UI-Text der Plattform (siehe Grundsätze).

Eine unbekannte Record-ID und eine existierende, aber nicht-öffentliche ID (z. B. Status draft) beantwortet dieser und jeder andere öffentliche Endpunkt identisch mit „nicht gefunden" — die beiden Fälle sind für eine anonyme Anfrage ununterscheidbar, aus demselben Grund wie bei der HTML-Seite (siehe Datenschutzmodell).

GET /api/v1/records/{id}/versions¶

Alle veröffentlichten Versionen eines öffentlichen Records, älteste zuerst. Jeder Eintrag:

{
  "label": "1.0",
  "publishedAt": "2026-09-14T10:00:00+00:00",
  "hash": "e823c28da19e1a6bddd66009b7977dc25195da26f4afa745b59afb234a20f782",
  "url": "https://www.veraificator.com/r/PILOT-2026-0002/v/1.0"
}

GET /api/v1/records/{id}/versions/{label}¶

Der Snapshot einer bestimmten Version (z. B. 1.0), zusammen mit ihrem recordHash — unabhängig davon, ob diese Version noch die aktuelle ist. Da veröffentlichte Versionen unveränderlich sind (siehe Versionierung), bleibt diese Antwort für ein gegebenes {id}/{label}-Paar für alle Zeit identisch.

GET /api/v1/records/{id}/jsonld¶

Dieselben Daten als JSON-LD, auf Basis von schema.org, mit Content-Type: application/ld+json. Nützlich für Systeme, die strukturierte Daten generisch weiterverarbeiten, ohne das verAIficATor-eigene Schema zu kennen. Die HTML-Seite selbst verlinkt auf dieses Dokument, statt es einzubetten (Details dazu in Sicherheit).

GET /api/v1/stats¶

Anonymisierte, plattformweite Kennzahlen — nichts davon lässt sich auf eine einzelne Person, einen einzelnen Record oder eine einzelne Institution zurückführen:

{
  "records": {"total": 2, "published": 1, "pending": 1, "withdrawn": 0},
  "workTypes": {"projektarbeit": 1},
  "contributionLevels": {"A0": 0, "A1": 2, "A2": 1, "A3": 2, "A4": 1},
  "verificationLevels": {"V0": 0, "V1": 2, "V2": 4, "V3": 0},
  "researchCriticalAI": {"yes": 1, "no": 0},
  "authorEvaluations": 0,
  "externalEvaluations": 0,
  "effortDistribution": {},
  "reuse": {},
  "evaluatorWelcome": {}
}

(Echte Antwort vom Stand dieser Dokumentation; die Zahlen wachsen mit dem Pilot.) records zählt Records nach ihrem aktuellen Status; alle übrigen Felder zählen Angaben aus den Snapshots der jeweils aktuellen Version bzw. aus Evaluationsantworten, aggregiert über alle Records. Ein Antwortwert taucht in workTypes, effortDistribution, reuse und evaluatorWelcome nur auf, wenn ihn mindestens eine Person tatsächlich gewählt hat — eine fehlende Kategorie bedeutet „bisher niemand", nicht „0 %".

GET /api/v1/schema¶

Die festen Vokabulare, die zum Interpretieren eines Records nötig sind, ohne sie aus Beispieldaten erraten zu müssen:

{
  "disclosureSchemaVersion": "0.3",
  "evaluationSchemaVersion": "0.1",
  "platformVersion": "0.3.1",
  "statusVocabulary": {
    "draft": "Entwurf",
    "self_declared": "Self-Declared",
    "pending_full_disclosure": "Self-Declared / Pending Full Disclosure",
    "published": "Published",
    "amended": "Amended",
    "withdrawn": "Withdrawn"
  },
  "contributionLevels": {
    "A0": "A0 – None",
    "A1": "A1 – Technical / Editorial Assistance",
    "A2": "A2 – Advisory Assistance",
    "A3": "A3 – Co-Productive Assistance",
    "A4": "A4 – Delegated Task"
  },
  "verificationLevels": {
    "V0": "V0 – No documented verification",
    "V1": "V1 – Plausibility Review",
    "V2": "V2 – Source / Data Verification",
    "V3": "V3 – Independent Verification"
  }
}

GET /api/v1/docs¶

Die interaktive, automatisch aus den API-Definitionen erzeugte Dokumentation (OpenAPI). Sie ist immer aktuell zum tatsächlich ausgelieferten Code, da sie aus demselben Quelltext entsteht, der auch die Endpunkte implementiert.

Institutionelle Endpunkte¶

Nur nach Anmeldung und ausschließlich für die eigene Institution erreichbar (siehe Einsatz in Institutionen für das Mandantenmodell):

GET /api/v1/institutions/{slug}/records — paginierte, private Registerliste der Institution (Name, Matrikelnummer, Studiengang, Semester, Modul, Kohorte, betreuende Person, interne Referenz u. a.).
GET /api/v1/institutions/{slug}/records.csv — dieselbe, aktuell gefilterte Liste als CSV-Download — das programmatische Gegenstück zum CSV-Export im institutionellen Bereich.

Eine unbekannte oder fremde slug beantwortet auch diese Endpunkte mit „nicht gefunden" statt „kein Zugriff" — dieselbe Regel wie beim HTML-Bereich.

Administrationsendpunkt¶

GET /api/v1/admin/stats liefert alles aus /stats, ergänzt um Betriebskennzahlen (Nutzer:innen- und Institutionenzahl, offene Evaluationen, Verbesserungsvorschläge nach Status) — weiterhin ohne Aufschlüsselung nach Person oder Institution. Nur für die Plattform-Administration; jede andere anfragende Person erhält hier ausdrücklich „kein Zugriff" (nicht „nicht gefunden") — die Existenz dieses Endpunkts ist kein Geheimnis, im Unterschied zu einem institutionellen Mandanten-Namen.

Caching und Stabilität¶

Öffentliche Antworten sind kurz cachebar (aktuell 60 Sekunden) und damit für den Einbau in andere Systeme (Bibliothekskataloge, institutionelle Dashboards, Repositorien) geeignet, ohne bei jedem Aufruf eine neue Anfrage gegen die Plattform auszulösen. Das Schema einer bereits veröffentlichten Version ändert sich nie rückwirkend (siehe Versionierung); künftige Schema-Änderungen erhöhen die disclosureSchemaVersion, ohne bestehende Versionen zu berühren.