Schnittstellen im Überblick

Der tibi-server spricht vier Sprachen: REST, SSE-Streams, MCP und OpenAPI. Alle hängen unter /api/v1 (außer /metrics). Quelle: internal/controller/setup.go.

API-Baum im Überblick

/api/v1
├── System:  /login  /token/_scopes  /llm/*  /audit  /admin/*  /version  /mcp
├── Projekt: /_/:project/:collection …  /_/:project/_actions/:action
│            /_/:project/_/assets/…  /_/:project/_/admin/…
└── Schema:  /_openapi/:project
/metrics  (Prometheus, außerhalb)

REST: System gegen Collection

System-Endpunkte

Methode	Pfad	Wofür
GET	/api/v1/version	Lebenszeichen ({"version":"…"})
POST	/api/v1/login, /api/v1/login/impersonate	JWT holen / als Admin schlüpfen
GET	/api/v1/token/_scopes	Gültige PAT-Scopes auflisten
POST / GET	/api/v1/llm/chat, /api/v1/llm/providers	Chat (ohne Secrets) / Provider-Namen
GET	/api/v1/audit	Audit-Logs (audit.read)
GET / POST	/api/v1/admin/embedding/status, /api/v1/admin/shutdown	Embedding-Status / Stop (server.shutdown)

Collection-Endpunkte

Methode	Pfad	Wofür
GET / POST	/_/:project/:collection	Suchen / anlegen
GET	/_/:project/:collection/_count, /_facet, /_queue	Zählen / Facetten / Warteschlange
GET / PUT / DELETE	/_/:project/:collection/:id	Lesen / ersetzen / löschen
PUT / DELETE	/_/:project/:collection (ohne ID)	Bulk-Update / Bulk-Delete
GET	/_/:project/:collection/:id/:field, …/:field/*path	Einzelnes Feld / Datei
GET / POST	/_/:project/_actions/:action	Hook-Aktion ohne Collection
GET	/_/:project/_/assets/:name/*path	Statische Assets

Trick für lange Filter: POST mit Header X-HTTP-Method-Override: GET — der Body wird zur Query.

Projekt-Admin

Methode	Pfad	Recht
POST	/_/:project/_/admin/reload	project.reload
POST / GET	/_/:project/_/admin/regenerate-search, …/search-worker/status	project.regenerate-search
GET	/_/:project/_/admin/embedding/status	Projekt-Admin
GET / POST / DELETE	/_/:project/_/admin/backup…	project.backup
GET / POST / DELETE	/_/:project/_/admin/snapshots…	project.snapshot

Antworten sind gzip-komprimiert — außer .pdf, .mp4, .jpg, .jpeg, .png und dem Pfad /metrics —, Body-Limits kaskadieren (Server → Projekt → Collection). Erstellen meldet 201, Löschen 204 — außer das Projekt will Legacy-Codes.

SSE (Echtzeit und Fortschritt)

• Der Realtime-Hub ist ein In-Memory-Pub/Sub je Projekt: benannte Kanäle, fester Ringpuffer (Standard 256), Nachhol-Optionen (LastN, MaxAge, TTL).
• Volle Kanäle werfen wahlweise Alt oder Neu weg — langsame Leser blockieren nie den Server.
• Kein fertiger Abo-Endpunkt: Der Server liefert keine HTTP-Route für Collection-Abos. Du erreichst den Hub nur über Hooks (channel.send / channel.subscribe) — typisch als eigene Action (/_/:project/_actions/:action), die du selbst als SSE auslieferst.
• text/event-stream liefert der Server fertig nur an zwei Stellen: POST /api/v1/llm/chat (Chat-Streaming) und Backup-Analyse-Download (.../admin/backup/analyze-download). Snapshot-Streaming ist dagegen Datei-Download mit RAM-Begrenzung, kein SSE.
• Backup- und Snapshot-Läufe melden Fortschritt als Event-Stream. Bricht der Stream ab, war es das Netzwerk — der Lauf selbst geht weiter.

MCP (KI-Werkzeuge)

Fakt	Wert
Transport	Streamable-HTTP, JSON-RPC 2.0
Route	fest POST + GET /api/v1/mcp — ein gesetztes mcp.route/MCP_ROUTE wird ignoriert (Routing hart in setup.go)
Auth	nur PAT via X-Auth-Token — kein JWT, kein Admin-Token
Rechte	jede Prüfung nutzt die gleichen Gates wie REST (nichts kopiert)
Ergebnis-Deckel	mcp.maxResultItems (Standard 100)
Admin-Werkzeuge	nur mit mcp.allowAdminActions: true, weiter pro Scope begrenzt

MCP-Tools auflisten (describe)

curl -X POST http://localhost:8080/api/v1/mcp \
  -H "X-Auth-Token: tibi_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OpenAPI-Generator

GET /api/v1/_openapi/:project erzeugt die Spezifikation deines Projekts frisch aus Config und Collections. Nutze sie für Client-Generierung und als Klick-Referenz. Die Version oben (/api/v1/version) sagt dir, ob Server und Spec zusammenpassen.

Welche Referenz wofür

Frage	Antwort liegt in
Wie heißt Config-Schlüssel X?	Server-Konfiguration
Wer darf Endpunkt Y?	Sicherheit (Tokens, Scopes)
Läuft der Server gesund?	Betrieb und Beobachtung (Version, Metriken)
Wie frage ich Daten ab?	Projekt-Seiten ab Begriffe
Was ist Tibi überhaupt?	Was ist Tibi?

Verifiziert am 68b4278 2026-10-15 (tibi-server)