COMPASS-Doku
ENDE

REST-Referenz

Basis-URL: $COMPASS_URL (Vertrags-Standard http://<host>:8080/api/v1). Jede Anfrage außer GET /version braucht eine X-Compass-Key-Kopfzeile. Alle Zeiten ISO-8601 UTC. Diese Referenz enthält keinen DELETE-Endpunkt — Aussagen, Prozesse, Lehren und jeder andere Datensatz werden abgelöst oder beendet, nie gelöscht (im Code existieren einige wenige, schmale und geprüfte Ausnahmen; siehe den Abweichungs-Hinweis am Ende dieser Seite).

Fehler sehen immer so aus: {"detail": "<Satz in Klartext>", ...Felder}. Ein 409 nennt den kollidierenden Datensatz; ein 422 nennt das betroffene Feld. Unbekannte Felder in einem Schreib-Body werden mit 422 abgewiesen (jedes Eingabe-Modell erbt extra="forbid").

Diese Seite listet nur Endpunkte, die sowohl im Vertrag als auch im laufenden Code existieren, gruppiert wie der Vertrag selbst gruppiert. Spalte Auth: ro = Lese-Schlüssel reicht, rw = Schreib-Schlüssel nötig, bruecke = auch mit einem bruecke-Schlüssel erreichbar.

Subjekte

Methode & Pfad Auth Was es tut
GET /subjekte ro Subjekte auflisten ({id, typ, ref_id, titel}).
POST /subjekte rw Subjekt anlegen; idempotent auf (typ, ref_id).

Sachen

Methode & Pfad Auth Was es tut
GET /sachen ro Sachen auflisten. Filter: bereich, stufe, suche, persona (Eigentum), sichtfeld (Sichtbarkeit), alle, limit. sichtfeld und persona beantworten bewusst verschiedene Fragen — siehe Konzepte. Je Eintrag anzahl_geltend (geltende Aussagen, alle Arten).
GET /sachen/{slug} ro Eine Sache plus ihre Aussagen, aufgeteilt in gilt / abgeloest / offen / hypothesen. Jede Aussage trägt ihren Prüfstand mit (pruefstand, pruefweg_letzter_lauf): ungeprueft heißt kein Prüfweg oder nie gelaufen.
POST /sachen rw Sache anlegen; idempotent auf slug (200, wenn sie schon existiert). persona_slug macht daraus eine Persona-Regel statt einer Firmenregel.

Regelbuch

Methode & Pfad Auth Was es tut
GET /regeln/wirkung ro Wirkt die Regel? Je Regel, die aus einer Lehre entstanden ist, wie oft derselbe Fehler nach „gilt seit" wieder auftrat, verglichen mit einem gleich langen Zeitraum davor (wiederholt_lehre_id, transitiv gezählt). Vier Gruppen: wirkt (mindestens halbiert), haeufiger, zu_frueh (gilt noch keine 14 Tage — keine Zahl, nicht 0), nicht_messbar. alle=true nimmt Regeln ohne Lehre dazu; sie bekommen grund='ohne_lehre' und ebenfalls keine Zahl. Kein Modell, keine Schätzung.
GET /regelbuch ro Lesende „gedruckte" Ansicht jeder Sache mit aktuell geltender Regel, nach Bereich gruppiert. bereich= filtert das angezeigte Kapitel; bereiche/gesamt in der Antwort sind immer die vollständige, ungefilterte Zusammenfassung. Das ist Etappe A einer dreistufigen Migration von CLAUDE.md §0 in den Kern — siehe die Anleitung.

Aussagen

Methode & Pfad Auth Was es tut
POST /aussagen rw Neue Aussage schreiben. 409 mit der geltenden Aussage, wenn bereits eine regel gilt und ersetzt fehlt; 422 bei unbekannter Sache, einer Hypothese ohne frist+pruefweg_slug, oder Stufenverstoß.
GET /aussagen/{id} ro Eine Aussage plus ersetzt_von/ersetzt (die Ablösekette).
POST /aussagen/{id}/status rw Status ändern (widerlegt|offen|vorlaeufig|gilt) — nur Hypothesen und offen/vorläufig.
POST /aussagen/{id}/beenden rw Eine geltende Aussage ohne Nachfolger beenden (status=abgeloest, gilt_bis=now()). 409, wenn sie gerade nicht gilt ist.
GET /gilt/{sache} ro Die eine geltende Regel, oder 404 mit {detail, offen}. persona= filtert nach Sichtbarkeit (403, wenn die Sache außerhalb liegt, außer alle=true).
GET /gilt-am/{sache} ro Was an einem Datum galt, mit Status. Gleiches Sichtbarkeits-Verhalten wie GET /gilt/{sache}.
GET /warum/{sache} ro Die Regel, ihr Entscheidungstext, ihre Historie, das letzte Prüfweg-Ergebnis.
GET /konflikte ro Sachen, bei denen etwas nicht zusammenpasst. Jeder Eintrag trägt art: mehrere_geltende_aussagen (mehrere geltende Aussagen derselben Art zur selben Sache, mit unterschiedlichem Text, von denen keine die andere ablöst — dazu anzahl_aussagen und anzahl_subjekte), stufenverstoss, ungepruefte_stufe oder widerspricht (eine gesetzte WIDERSPRICHT-Kante, mit grund, quelle und gesetzt_von). Zweimal derselbe Wortlaut zählt nicht, eine abgelöste Aussage auch nicht, eine beendete Kante auch nicht. Und seit dem 29.09.2026 auch nicht: eine Sache, die lauter Antworten auf verschiedene Fragen gesammelt hat — jede Aussage der Gruppe trägt quelle = frage:<n>, und alle zeigen auf verschiedene Fragen. Gemeldet bleibt, wo eine Aussage keine Quelle hat, eine fremde Quelle trägt, oder wo zwei Antworten auf dieselbe Frage nebeneinanderstehen.
POST /widersprueche rw Zwei Aussagen widersprechen sich — mit Grund, und ohne Konfidenzwert. Setzt ein Mensch (quelle=mensch) oder eine beantwortete Klickfrage (quelle=frage mit frage_id); kein Automat schreibt hier. 422 ohne Grund oder bei einer Aussage gegen sich selbst, 404 bei unbekannter Aussage, 409 wenn dieses Paar schon eine geltende Kante hat.
POST /widersprueche/{id}/beenden rw Den Widerspruch zurücknehmen: beendet_am/beendet_von werden gesetzt, gelöscht wird nichts. Danach fällt die Kante aus GET /graph und GET /konflikte, bleibt aber lesbar. 409, wenn sie schon beendet ist.
GET /aussagen/{id}/nachweise ro Welche Dokumente diese Aussage belegen. Je Eintrag Slug, Titel und Fassung des Dokuments, dazu bestaetigt_am/bestaetigt_von — leer heißt: noch niemand hat hingesehen. Zurückgenommene Kanten kommen erst mit ?beendet=true.
POST /aussagen/{id}/nachweise rw Ein Dokument als Beleg anhängen ({dokument_slug, bemerkung?}), unbestätigt. Anhängen und Bestätigen sind zwei Schritte. 409, wenn dasselbe Dokument die Aussage schon belegt oder wenn das Dokument beendet ist.
POST /nachweise/{id}/bestaetigen rw Festhalten, dass jemand diesen Beleg angesehen hat. Setzt Zeitpunkt und Namen — und sonst nichts: der Status der Aussage bleibt, wie er ist. 409 beim zweiten Mal.
POST /nachweise/{id}/beenden rw Die Kante zurücknehmen: beendet_am wird gesetzt, gelöscht wird nichts. Sie fällt aus der Liste und aus GET /warum/{sache}, bleibt lesbar, und dasselbe Dokument darf danach erneut angehängt werden.

Stufen

Welche Stufen es gibt und in welcher Ordnung, sagt der Mandant — Vorgabe leer. COMPASS bringt kein eigenes Stufen-Vokabular mit.

Route Recht Was sie tut
GET /sachen-stufen ro Die aktiven Stufen dieses Mandanten, allgemeinste zuerst: [{slug, rang, titel, erstellt_am}]. Leere Liste = keine Stufen konfiguriert, und das heißt: jede an einer Sache gesetzte Stufe gilt als ungeprüft, nicht als in Ordnung.
PUT /sachen-stufen rw Setzt die ganze Ordnung: {stufen: [{slug, titel?}]}. Die Reihenfolge ist der Rang, allgemeinste zuerst — kein rang-Feld, das der Aufrufer selbst vergeben könnte. Was nicht mehr vorkommt, bekommt entfernt_am und bleibt stehen (gelöscht wird nicht). 422 bei unerlaubtem Slug oder doppeltem Eintrag.

Hypothesen

Methode & Pfad Auth Was es tut
POST /hypothesen rw Hypothese anlegen (art=hypothese, status=vorlaeufig). frist und pruefweg_slug sind Pflicht.
POST /hypothesen/{id}/bewerten rw Auflösen: bestaetigt|widerlegt|verlaengert (mit neue_frist).
GET /hypothesen ro Auflisten, optional faellig=true für fällige.

Prüfwege

Methode & Pfad Auth Was es tut
POST /pruefwege rw Prüfweg anlegen oder upserten. 422, wenn befehl nicht auf der Allowlist steht oder ein schreibendes Muster enthält (>, rm, DELETE, git push, …).
GET /pruefwege ro Prüfwege auflisten, inklusive der rohen Ursachen-Spalten (erfuellt, werkzeug_fehlt_serie, reparatur_noetig, …).
POST /pruefwege/{slug}/run rw Ausführen (30 s Timeout), Ergebnis speichern, Fakt schreiben. Ein sauberer Lauf löst einen offenen Abweichungs-Zustand dieses Prüfwegs auf.
POST /pruefwege/{slug}/beenden rw Prüfweg beenden — grund und von sind Pflicht. Er läuft nicht mehr im Nachtlauf, erscheint nicht mehr als Abweichung und zählt im Rundgang nicht mehr mit; /run antwortet danach 409. Die Zeile bleibt lesbar, samt letztem Lauf. Gelöscht wird nicht.

Abweichungen

Eine Abweichung heißt: das Ergebnis eines Prüfwegs passte nicht zur Erwartung seiner Regel. Die Ursache ist immer eine von drei, nie geraten: verstoss (Verstoß), werkzeug_fehlt (ein bekanntes Werkzeug-fehlt-Muster gewinnt immer gegen jede andere Lesart), oder unklar (die Erwartung selbst ließ sich nicht auswerten).

Methode & Pfad Auth Was es tut
GET /abweichungen ro Abweichungen auflisten, mit ursache, stumm (true ab 3 aufeinanderfolgenden werkzeug-fehlt-Läufen) und fertigem ticket_text. Optional seit=.
POST /abweichungen/{pruefweg_slug}/verfolgen rw Als verfolgt markieren, optional ticket anhängen. 409, wenn der Prüfweg gerade nicht abweicht.
POST /abweichungen/{pruefweg_slug}/regel-ueberholt rw Aus einer Abweichung eine Schaltzentrale-Frage stellen („Regel behalten oder ablösen"). 422 ohne geltende Regel auf dem Prüfweg.
POST /abweichungen/{pruefweg_slug}/pruefweg-kaputt rw Den Prüfweg selbst als kaputt markieren — nimmt ihn aus der GET /offen-Ampel, nicht aus GET /abweichungen.

Prozesse

Methode & Pfad Auth Was es tut
POST /prozesse rw Prozess anlegen, oder neue Version, wenn der slug existiert (alte Version bekommt gilt_bis).
GET /prozesse ro Die höchste Version je Slug. alle=true zeigt auch abgelöste/beendete. Je Eintrag anzahl_schritte und anzahl_luecken.
GET /prozesse/{slug} ro Die höchste Version, ihre Schritte, Regeln je Schritt, luecken (Schritte ohne Regel und ohne frei=true). ueberholt: true, wenn beendet. Dazu versionen: jeder Stand dieses Prozesses mit gilt_seit und gilt_bis.
GET /prozesse/{slug}?version= ro Genau diesen Stand, mit seinen Schritten. Damit ist nachlesbar, was vor einer Änderung galt: ein Schritt, der aus der Liste genommen wurde, steht im vorherigen Stand vollständig da — gelöscht wird nichts. Ein Stand, den es nicht gibt, ist 404, und die Antwort nennt die vorhandenen.
GET /prozesse/{slug}/bild/{key} ro 302 auf das Bild des Schritts, oder 404.
POST /prozesse/{slug}/beenden rw Einen Prozess ohne Nachfolgeversion beenden. 409, wenn bereits beendet.

Schaltzentrale

Methode & Pfad Auth Was es tut
POST /fragen rw Eine Frage mit mindestens zwei Optionen stellen, jede mit folge (Konsequenz). Sonst 422.
GET /offen ro Alles, was einen Klick braucht, je Quelle mit Zustand ruhig|unbekannt|achtung. Sieben Quellen, darunter postfach (Nachrichten und Aufträge der Agenten an den Menschen). Fragen-Einträge tragen bereich, gestellt_von und je Aktion folge. Jeder Eintrag trägt herkunft_art (mensch|agent|rundgang|null) aus der vom Kern belegten Herkunft — null, wo keine Spur existiert.
GET /fragen/seit ro Beantwortete Fragen seit einem Zeitpunkt — Frage, Antwort, Sache, wer geantwortet hat. (Noch nicht im Vertrag; siehe den Abweichungs-Hinweis.)
POST /fragen/{id}/antwort rw, bruecke Eine Frage beantworten; schreibt eine Entscheidung, löst die geltende Regel ab, wenn die gewählte Option das vorsieht.
POST /offen/hinweis/{id}/erledigt rw Einen Hall-of-Lessons-Hinweis als gelesen markieren (dieselbe Wirkung wie POST /lehren/{id}/gelesen).
POST /offen/{typ}/{id}/erledigt rw Jeden anderen offenen Eintrag erledigen (Frage, Freigabe, Design-Übergabe, Konflikt).

Kern, Graph & Gedächtnis

Methode & Pfad Auth Was es tut
GET /kern/{subjekt_id} ro Die geltenden Regeln als Markdown, nach Bereich gruppiert, plus hash.
GET /graph ro Knoten und Kanten rund um eine Sache, bis tiefe. Tatsächlich heute erzeugte Kantentypen: GEHOERT_ZU, ERSETZT, GILT_AN, GEPRUEFT_DURCH, BETRIFFT — siehe den Abweichungs-Hinweis für Kantentypen, die der Vertrag beschreibt, die der Graph-Endpunkt aber noch nicht erzeugt. Mit tage= ein Zeitfenster auf gilt_seit; weggelassen heißt alles.
GET /graph/ansichten ro Gespeicherte Graph-Ansichten dieses Mandanten, jüngste zuerst (alle=true auch die beendeten). Eine Ansicht ist eine gemerkte GET /graph-Anfrage: Ausgangsknoten, tiefe, tage, Name — der Kern rechnet sie nicht nach.
POST /graph/ansichten rw Ansicht anlegen. 422 bei unbekannter Sache, leerem Namen, tiefe außerhalb 1..5 oder tage <= 0 (hier wird abgewiesen, nicht geklemmt wie in GET /graph); 409, wenn unter den offenen Ansichten schon eine mit diesem Namen steht.
POST /graph/ansichten/{id}/beenden rw Ansicht beenden — sie verschwindet aus der Liste und bleibt stehen (kein DELETE). 409, wenn sie schon beendet ist.
POST /ereignisse rw, bruecke Ereignis erfassen (chat|klick|messung|pr|lauf|vorlage). Idempotent auf quelle_ref.
GET /ereignisse ro Ereignisse eines Subjekts auflisten, optional seit=.
GET /suche ro Volltextsuche über Aussagen und Ereignisse. Antwort {treffer, gesamt, abgeschnitten, weiter} — gesamt zählt nach dem Sichtfeld-Filter, weiter ist der offset der nächsten Seite oder null. persona= filtert Aussage-Treffer nach Sichtbarkeit; Ereignis-Treffer werden nie gefiltert (Ereignisse tragen kein bereich).
GET /regelwerk/abdeckung ro {entscheidungen_gesamt, mit_aussage, ohne_aussage, quote} — wie viel des Entscheidungs-Logs eine passende Aussage trägt. quote ist null, nie 0, bei leerem Universum.

Import / Export

Methode & Pfad Auth Was es tut
POST /import/claude-md ro Vorschau: ein deterministischer Scan ohne Sprachmodell (art=claude-md|agents-md|cursor-rules, für alle drei derselbe Scan) nach Überschriften mit einem Anweisungssatz darunter, oder Stichpunkten/Nummerierungen mit einem Imperativ-Marker am Anfang. Jeder Vorschlag trägt regel_text im Originalwortlaut. Schreibt nichts. Der Datei-Weg (file) prüft vorher Größe (max. 1 MB) und ob die Datei überhaupt Text ist — beides 422 mit feld: "file" und byte; im Fehlerfall wird nichts gelesen und nichts geraten.
POST /import/claude-md/apply rw Den geprüften Vorschlag schreiben — Sache und Aussage in einem Aufruf (regel bei art=claude-md, fakt bei agents-md/cursor-rules). Idempotent über quelle_ref; eine bestehende geltende Regel im Widerspruch oder ein abweichender Inhalt auf derselben Quellzeile werden gemeldet (konflikt/quelle_ref_widerspruch), nie still überschrieben.
POST /import/decisions rw, bruecke Entscheidungen im Bulk importieren, über eine Z-Nummer verankert. Idempotent auf quelle=Z.<n>; ein Widerspruch im Inhalt unter demselben Schlüssel, oder eine zweite gilt-Regel ohne auflösbares ersetzt_z, landet in widerspruch — der Aufruf bleibt trotzdem 200.
GET /export/claude-md-section0 ro Das Regelwerk als Markdown-Text.
GET /export/agents-md ro Derselbe Inhalt, für AGENTS.md geformt.
GET /export/cursor-rules ro Ein ZIP mit Cursor-Regeldateien.

Kundendaten-Export ("Eure Daten gehören euch")

Der ganze Bestand eines Kunden zum Mitnehmen — anders als die Werkzeug-Formate oben (die nur die geltenden Regeln in ein fremdes Konfigurationsformat gießen), umfasst dieser Export jede Aussage mit ihrer Geschichte, Lehren (auch beendete), Gedächtnis, Prozesse (alle Versionen), Prüfwege, Fragen und Entscheidungen, Personas und Firmengedächtnis.

Methode & Pfad Auth Was es tut
GET /export/kopf ro Nur {format_version, stand, kunde, zaehlung} — ohne Datensätze, schnell.
GET /export ro ?format=json (NDJSON: eine Kopfzeile, dann eine Zeile je Datensatz mit teil) oder ?format=markdown (lesbares Regelwerk: je Bereich/Sache die geltende Regel, „Frühere Fassungen", Entscheidungen chronologisch, Lehren kurz — kein LLM, nichts erfunden). Beide StreamingResponse.

Nie enthalten: Schlüssel/Hashes, Sitzungen/Anwesenheit. Zeilenschutz wie überall — ein anderer Kunde sieht mit seinem eigenen Schlüssel nur seinen eigenen (leeren) Export.

Personas

Methode & Pfad Auth Was es tut
GET /personas ro Personas mit Kennzahlen (anzahl_regeln, anzahl_gedaechtnis), vorlage_name, slack. slack ist eine Markierung, die ihr setzt und hier wieder abruft: COMPASS sendet selbst nichts an Slack. Ein Dienst, den ihr anschließt, kann sie auslesen und danach handeln — ohne einen solchen Dienst bleibt sie folgenlos. Für Ereignisse, die COMPASS von sich aus nach außen meldet, nimm die ausgehenden Aufrufe weiter unten.
GET /personas/{slug} ro Vollständiger Datensatz plus sichtfeld, regeln, gedaechtnis_letzte (10 jüngste). 404 bei unbekanntem Slug.
PUT /personas/{slug} rw Vollständiger Upsert — jedes nicht mitgeschickte Feld wird auf den Standard zurückgesetzt, kein Teil-Update.
GET /personas/{slug}/brief ro Der deterministische Markdown-Brief. ?max_gedaechtnis=&budget=&max_lehren=.
GET /personas/{slug}/brief/stats ro Dieselben Zahlen, aus denen der Brief gebaut wird, als strukturierte Daten.
GET /personas/{slug}/gedaechtnis ro Volltextsuche im Gedächtnis einer Persona (eigenes plus sichtbares Firmen-Gedächtnis).
POST /personas/{slug}/gedaechtnis rw Gedächtnis-Eintrag hinzufügen (fakt|feedback|ereignis).
PATCH /personas/{slug}/gedaechtnis/{id} rw Einen Gedächtnis-Eintrag beenden (gilt_bis).
POST /personas/gedaechtnis/import rw Gedächtnis im Bulk importieren, idempotent auf quelle_ref. persona_slug=null schreibt Firmen-Gedächtnis.
GET /persona-vorlagen ro Der Vorlagen-Katalog.
GET /persona-vorlagen/{slug} ro Eine Vorlage.
POST /persona-vorlagen/vorschlag ro Bis zu 3 Vorlagen gegen einen Freitext-Bedarf ranken (Stichwort-Treffer, deterministisch).
POST /personas/from-vorlage rw Eine Vorlage in eine neue Persona kopieren. 409 bei Slug-Konflikt.
GET /personas/{slug}/beurteilung ro Personalakten-Ansicht: offene Rollen-Vorschläge, Gelungenes, selbst gemeldete Fehler, Rückfälle, Rückmeldungen des Menschen.
POST /personas/{slug}/rollen-vorschlag rw Eine Änderung an aufgabe|koennen|stil|grenzen vorschlagen, mit mindestens einer Lehre belegt; stellt eine Schaltzentrale-Frage.

Bereiche

Methode & Pfad Auth Was es tut
GET /bereiche ro Die Bereiche-Registry, alphabetisch.
POST /bereiche rw Einen Bereich hinzufügen. 409, wenn er existiert, 422, wenn der Name kein kebab-Slug ist.

Agents: Anwesenheit und Postfach

Methode & Pfad Auth Was es tut
POST /agents/herzschlag ro Lebenszeichen einer Sitzung (persona_slug, sitzung, client, status?). Upsert; eine Sitzung gilt 15 Minuten nach ihrem letzten Herzschlag als online.
POST /agents/offline ro Eine Sitzung ausdrücklich abmelden.
GET /agents ro Jede aktive Persona mit Anwesenheit, Sitzungen, Postfach-Zählern, live berechneter Gehirn-Last.
POST /agents/{persona}/nachrichten rw (oder ro mit von_persona) Nachricht senden. Genau eines von von_persona/von_mensch=true ist Pflicht. art=auftrag prüft zusätzlich leitung/nimmt_auftraege_von.
GET /agents/{persona}/nachrichten ro Postfach einer Persona; sitzung= markiert unzugestellte Nachrichten als Nebenwirkung als zugestellt.
POST /agents/nachrichten/an-mensch rw (oder ro mit von_persona) Nachricht/Auftrag einer Persona AN den Menschen (von_persona/von_sitzung Pflicht, an_persona=NULL, an_mensch=true). Erscheint in GET /offen als Quelle postfach.
GET /agents/nachrichten ro Alle Nachrichten des Mandanten. Ohne Zeiger: neueste zuerst. an_mensch=true\|false grenzt auf das Postfach des Menschen bzw. auf Persona-Nachrichten ein. seit_id=<id> liest fortlaufend: nur Nachrichten nach dieser id, aufsteigend — der nächste Zeigerwert ist die id des letzten Eintrags der Antwort, eine leere Antwort heißt „nichts Neues". seit=<zeitpunkt> filtert nach Sendezeit (einschließend) und taugt nicht als Zeiger: gleiche Sendezeiten sind nicht unterscheidbar, und der eigene letzte Eintrag käme jedes Mal wieder.
POST /agents/nachrichten/{id}/gelesen ro Eine Nachricht als gelesen markieren.
POST /agents/nachrichten/{id}/status rw Status eines Auftrags setzen (offen|angenommen|erledigt|abgelehnt).

Hall of Lessons

Methode & Pfad Auth Was es tut
POST /lehren rw Eine Lehre schreiben (fehler|gelungen|hinweis). ursache ist Pflicht bei fehler; bereich ist bei allen Pflicht (unsortiert, solange die Zuordnung offen ist). Idempotent auf quelle_ref.
PATCH /lehren/{id} rw Bereich oder Wortlaut einer bestehenden Lehre korrigieren. Nur der Ersteller; eine beendete Lehre bleibt stehen (409). Ein korrigiertes Feld wird ersetzt, nicht ergänzt — wer nur einen Teil des Textes sendet, verliert den Rest. Die Ursache ist auch hier nicht änderbar; muss sie anders lauten, löst eine neue Lehre die alte ab.
GET /lehren ro Auflisten, filterbar nach art, status, bereich, persona (Eigentum), sichtfeld (Sichtbarkeit), q (Volltext), offen_hinweise.
GET /lehren/{id} ro Eine Lehre plus ihre verknüpfte Frage und, falls zur Regel geworden, ihre Regel.
POST /lehren/{id}/aufnehmen rw Als gesehen und für richtig befunden markieren (status=aufgenommen). 409, außer sie war offen.
POST /lehren/{id}/regel-vorschlagen rw Eine Schaltzentrale-Frage stellen, um daraus eine Regel zu machen — schreibt die Regel nie direkt.
POST /lehren/{id}/beenden rw Beenden (gilt_bis=now()).
POST /lehren/{id}/gelesen rw Einen hinweis als gelesen markieren.
POST /lehren/{id}/antwort rw Auf einen hinweis antworten; schreibt zusätzlich einen Gedächtnis-Eintrag für dessen Persona.
GET /lehren/stats ro Zahlen nach Status und Art, diese Woche insgesamt, ungelesene Hinweise.
POST /lehren/import-gedaechtnis rw Einmaliger Import der dateibasierten Feedback-Gedächtnis-Einträge als fehler-Lehren. Unterstützt trocken=true (Trockenlauf).

Hall of Fame + Daumen

Methode & Pfad Auth Was es tut
GET /hall-of-fame ro Wochen-Rangliste inklusive Abzeichen.
GET /hall-of-fame/abzeichen ro Alle Abzeichen, jüngste Woche zuerst.
GET /hall-of-fame/quellen ro Welche Punktequellen aktuell feuern gegenüber nur in der Registry stehen.
POST /daumen rw Ein Daumen hoch, nur von einem Menschen — eine Persona als von bekommt 403. 409 bei einem zweiten Daumen derselben Person auf dasselbe Objekt.
POST /daumen/{id}/zuruecknehmen rw Einen Daumen mit einer Gegenbuchung zurücknehmen (409, wenn bereits zurückgenommen).
GET /daumen ro Daumen auflisten.
GET /personas/{slug}/daumen ro Daumen-Gesamtzahl einer Persona, diese Woche, 10 jüngste.

Statistik

Methode & Pfad Auth Was es tut
GET /statistik ro Sechs Blöcke (gehirn, koepfe, anwesenheit, arbeit, qualitaet, system), deterministisch in einer Transaktion berechnet, einmalig als stand zeitgestempelt.

Der Rundgang

(hieß früher „Der Verbesserer" — englisch „the rounds".)

Methode & Pfad Auth Was es tut
GET /rundgang ro Ergebnis von 23 festen Prüfungen über 6 Kategorien — Zahl, Schwelle, betroffene Datensätze je Prüfung; nie geraten. Antwort trägt zusätzlich modus (aus/rechnend/rechnend_lesend).
POST /rundgang/melden rw Steht der Modus auf aus: schreibt nichts. Sonst je Kategorie über der Schwelle einen hinweis einreichen. trocken=true wertet aus, ohne zu schreiben.
GET /rundgang/einstellungen ro Aktueller Modus des Mandanten + Ein-Satz-Erläuterung + die drei Stufen (aus/rechnend/rechnend_lesend) mit Titel/Beschreibung.
PUT /rundgang/einstellungen rw Setzt den Modus ({modus, von}). Standard nach Anlage eines Kunden: rechnend.
POST /rundgang/versenden rw Der Morgen-Bericht: ein Bündel-Mail je aktivem Mitglied über alle noch offenen Zustellungen, respektiert sofort/taeglich/nie.
GET /kunden/{slug}/mitgliedschaft/rundgang-einstellungen Sitzung Die eigene Zustellungs-Präferenz (sofort/taeglich/nie) für den Rundgang dieses Kunden.
PUT /kunden/{slug}/mitgliedschaft/rundgang-einstellungen Sitzung Setzt die eigene Präferenz ({zustellung}). Jedes Mitglied für sich selbst, keine Eigentümer/Verwalter-Schranke.

Webhooks — Ereignisse nach außen

COMPASS ruft raus, euer System nimmt an. Vollständige Anleitung samt Signaturprüfung und Beispiel: Ereignisse nach außen.

Methode & Pfad Auth Was es tut
POST /webhooks rw Webhook anlegen: {url, ereignisse}. Die Antwort enthält das geheimnis — nur dieses eine Mal. 422, wenn ausgehende Aufrufe auf dieser Installation nicht eingerichtet sind, ereignisse leer ist oder einen unbekannten Namen enthält, oder die Adresse nicht https:// ist bzw. ins private Netz zeigt.
GET /webhooks ro Die eigenen Webhooks, ohne Geheimnis.
POST /webhooks/{id}/test rw Eine Zustellung mit dem Ereignis ping einreihen, unabhängig von den abonnierten Ereignissen. 409, wenn der Webhook deaktiviert ist.
GET /webhooks/{id}/zustellungen?limit=50 ro Zustellungen, neueste zuerst — Versuch, Status, letzter HTTP-Code, letzter Fehler. Hier seht ihr nach, wenn etwas nicht ankommt.
POST /webhooks/{id}/deaktivieren rw Der Webhook hört auf zu senden und bleibt lesbar. 409, wenn er es schon ist. Gelöscht wird nichts.

Die fünf Ereignisnamen: regel.gesetzt, regel.abgeloest, abweichung.neu, abweichung.behoben, frage.beantwortet.

Firma

Methode & Pfad Auth Was es tut
GET /firma ro Die sechs Firmengedächtnis-Felder.
PUT /firma rw + Mensch Benannte Felder aktualisieren. Nur mit angemeldeter Person: ein Schlüssel allein bekommt 403. Ein Agent, der in der angemeldeten Sitzung einer Person arbeitet, darf es. Wer die Felder gesetzt hat, nimmt COMPASS aus der Anmeldung — ein mitgeschicktes von wird nicht übernommen.
GET /firma/stats ro Wie viele der sechs Felder gefüllt sind.

Mandanten & Version

Methode & Pfad Auth Was es tut
GET /kunde ro Der Mandant, dem der vorgelegte Schlüssel gehört ({slug, stufe, menschen, menschen_limit, name}).
GET /version keine {git_sha, gebaut_am, dienst, grund} — bewusst ohne Schlüssel erreichbar.

Beim Schreiben dieser Seite gefundene Abweichungen vom Vertrag

  • GET /graph erzeugt GEHOERT_ZU, ERSETZT, GILT_AN, GEPRUEFT_DURCH, BETRIFFT — und seit dem 28.09.2026 WIDERSPRICHT. Hier stand bis dahin, WIDERSPRICHT tauche „im laufenden Code nicht auf" und sei „als abgeleitet, nicht gespeichert, vermerkt": das erste stimmt nicht mehr, das zweite war schon damals die falsche Auskunft — sie ist die einzige gespeicherte Kante, und zwar mit Absicht (sie fällt aus einem Urteil, nicht aus einem Fremdschlüssel). Offen bleiben aus dem Vertrag ZEIGT und WIRKT_IN; keiner der beiden taucht heute im laufenden Code auf.
  • GET /fragen/seit (und sein MCP-Werkzeug seit_wann_neu) existiert im laufenden Code, ist aber noch nicht im Vertrag beschrieben. Hier dennoch dokumentiert, weil es ein stabiler, funktionierender Lese-Endpunkt ist — als dem Vertrag voraus markiert.
  • GET /api/v1/health existiert im laufenden Code, wird aber im Vertrag nicht erwähnt (dort steht nur GET /version) — deshalb hier ausgelassen.
  • Eine Reihe Endpunkte existiert im laufenden Code ohne jede Beschreibung im Vertrag: GET /aussagen/nachfolgerlos, POST /aussagen/ersetzt-nachziehen, GET /sachen/aufraeum, POST /sachen/{slug}/verabschieden, POST /sachen/{slug}/widerrufen, GET /personas/organigramm, POST /personal-vorschlaege, POST /personas/{slug}/verabschieden, DELETE /personas/{slug} (eine schmale, geprüfte Ausnahme — verweigert mit 409, außer die Persona hat keinerlei Spuren), sowie GET/POST /gedaechtnis, GET /gedaechtnis/stats, POST /gedaechtnis/backfill-bereiche. Keiner davon ist hier dokumentiert.