REST-API Überblick

Die REST-API unter /api/v1/ erlaubt Integrationen und Tools (inklusive des Obsidian-Plugins), Dokumente und Sammlungen über eine stabile JSON-Schnittstelle zu verwalten. Diese Seite erklärt Verhalten, das für alle Endpunkte gilt. Felder und Request-Bodies pro Operation sind in der OpenAPI-Referenz dokumentiert.

Basis-URL

Verwende dieselbe Origin wie deine deployte Orimora-Instanz:

Produktion: https://your-domain.example.com
Lokal (Vite): http://localhost:5173
Docker Compose (App-Service): http://localhost:3000, sofern du den Port nicht ummappst

Alle Pfade in diesem Dokument sind relativ zu dieser Basis (z. B. GET /api/v1/documents).

Authentifizierung

API-Schlüssel (Bearer)

Gehe in der Web-App zu Einstellungen → Entwickler und erstelle einen API-Schlüssel.
Schlüssel werden einmalig angezeigt und haben das Präfix kb_.
Sende den Schlüssel als Bearer-Token:

GET /api/v1/documents HTTP/1.1
Host: your-domain.example.com
Authorization: Bearer kb_your_key_here

Der Server ordnet den Schlüssel einem Nutzer und einem Team zu. Routen, die requireUser() verwenden, akzeptieren entweder eine normale Browser-Session oder dieses Bearer-Token.

Scopes

Jeder Schlüssel hat einen oder mehrere Scopes:

Scope	Typische Nutzung
`read`	Dokumente und Sammlungen listen und abrufen
`write`	Ressourcen anlegen und aktualisieren
`admin`	Operationen, die Team-weite Einstellungen ändern (sofern bereitgestellt)

Standard für neue Schlüssel ist read + write. Gestalte Integrationen so, dass sie den kleinstmöglichen notwendigen Scope verwenden.

Ratenbegrenzung

Bereich	Limit (Orientierung)	Hinweise
*Alle `/api/`-Routen**	100 Anfragen pro IP oder Nutzer pro 60 Sekunden	Globaler Guard in der Request-Pipeline; übersprungen für `GET /api/health`
Auth-Endpunkte	Strenger (z. B. Magic Link / OAuth)	Schützt vor Missbrauch; exakte Keys siehe Implementierung

Bei Begrenzung ist die Antwort 429 Too Many Requests mit JSON ähnlich zu:

{
  "error": "Too many requests",
  "retryAfterSeconds": 60
}

Erfolgreiche Antworten können enthalten:

X-RateLimit-Limit — maximale Anfragen pro Fenster
X-RateLimit-Remaining — verbleibend im aktuellen Fenster
Retry-After — vorhanden bei 429

Behandle 429 in Automation mit exponentiellem Backoff.

Pagination (`GET /api/v1/documents`)

Ohne updatedSince enthalten Listen-Antworten:

Feld	Bedeutung
`data`	Array von Dokumenten
`total`	Gesamtzeilen, die zu den Filtern passen (nicht nur diese Seite)
`limit`	Seitengröße (begrenzt, Default 25, max 100)
`offset`	Skip-Offset

Filtere die Liste mit diesen Query-Parametern:

Parameter	Bedeutung
`collectionId`	Auf eine Sammlung beschränken
`parentDocumentId`	Auf direkte Unterdokumente eines Dokuments beschränken
`title`	Exakter Titel-Match, case-insensitiv — für gezielte Existenzprüfungen (vom Plugin genutzt)
`status`	`published` oder `draft`
`tag`	Auf Dokumente mit diesem Tag beschränken (per Name, case-insensitiv). Den Parameter wiederholen (`?tag=a&tag=b`) für einen Mehrfach-Tag-UND-Filter — es passen nur Dokumente, die alle genannten Tags tragen
`limit` / `offset`	Seitengröße (Default 25, max 100) und Skip-Offset

Inkrementeller Sync (`updatedSince`)

Für Tools, die nur geänderte Dokumente seit einem Zeitpunkt benötigen:

Übergib updatedSince als ISO-8601-Zeitstempel (z. B. 2026-04-01T12:00:00.000Z).
Die Antwortform unterscheidet sich: Es gibt keine total/offset-Pagination in derselben Weise; der Server verwendet ein höheres effektives Limit für das Sync-Fenster.
Füge format=markdown zusammen mit updatedSince hinzu, um pro Dokument ein markdownText-Feld für Klartext-Sync zu erhalten (vom Obsidian Selective Pull genutzt).

Details siehe die Operation OpenAPI /api/v1/documents GET.

Request-Bodies: Markdown vs. TipTap-JSON

text: Markdown-String — der Server wandelt ihn intern in TipTap-/ProseMirror-JSON um.
content: rohes TipTap-JSON, falls du bereits strukturierten Inhalt hast (fortgeschrittene Integrationen).

Du verwendest beim Anlegen oder Aktualisieren von Body-Inhalt typischerweise das eine oder das andere, nicht beides.

Antworten und Fehler

Erfolgs-Payloads sehen meist so aus:

{
  "data": {
    /* resource */
  }
}

Listen-Endpunkte liefern { "data": [ … ] } plus Pagination-Felder, wie pro Route dokumentiert.

Fehler verwenden JSON mit einem error-String (und HTTP 4xx/5xx):

{ "error": "Document not found" }

HTTP	Typische Ursache
401	Fehlender oder ungültiger API-Schlüssel / Session
403	Authentifiziert, aber nicht erlaubt (z. B. Onboarding unvollständig)
404	Ressource nicht gefunden oder falsches Team
429	Rate-Limit
400	Validierung / ungültiges JSON

Webhooks

Dokument-Lifecycle-Events können in der Workspace konfigurierte Webhooks auslösen. Webhook-Zustellung, -Signierung und -Retries sind nicht Teil der /api/v1/-CRUD-Oberfläche; konfiguriere sie in der App-UI. Automation sollte trotzdem idempotente Handler verwenden und Signaturen verifizieren, wenn sie bereitgestellt werden.

OpenAPI

Dieselben Operationen sind als OpenAPI 3.1 für Codegeneratoren und die Starlight-UI verfügbar:

Interaktive API-Referenz →

Erzeuge die gebündelte Spec neu mit:

cd docs && yarn generate:openapi

(Läuft automatisch als Teil von yarn build im docs-Paket.)