---
title: 'Schnittstellen im Überblick'
description: 'REST, SSE, MCP, OpenAPI: was wofür gilt und wo die Referenz liegt.'
---

import { TabItem, Tabs } from '@astrojs/starlight/components';

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`.

```text title="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

<Tabs syncKey="api-sicht">
<TabItem label="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`) |

</TabItem>
<TabItem label="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.

</TabItem>
<TabItem label="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` |

</TabItem>
</Tabs>

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 |

```bash title="MCP-Tools auflisten (describe)" {2}
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](/server/konfiguration/) |
| Wer darf Endpunkt Y? | [Sicherheit](/server/sicherheit/) (Tokens, Scopes) |
| Läuft der Server gesund? | [Betrieb und Beobachtung](/server/betrieb/) (Version, Metriken) |
| Wie frage ich Daten ab? | Projekt-Seiten ab [Begriffe](/einstieg/begriffe/) |
| Was ist Tibi überhaupt? | [Was ist Tibi?](/einstieg/was-ist-tibi/) |

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