REST-API Überblick

import { Aside } from ‘@astrojs/starlight/components’;

Die REST-API unter /api/v1/ ist die stabile JSON-Schnittstelle für Integrationen (inkl. Obsidian-Plugin). Diese Seite beschreibt übergreifendes Verhalten; Einzelfelder stehen in der OpenAPI-Referenz.

Basis-URL

Identisch mit der Origin deiner Orimora-Instanz:

Lokal (Vite): http://localhost:5173
Docker (App-Port 3000): http://localhost:3000

Alle Pfade sind relativ zu dieser Basis.

Authentifizierung

API-Schlüssel (Bearer)

Einstellungen → Entwickler — neuen Schlüssel anlegen.
Präfix kb_, beim ersten Anzeigen sichern.
Header:

Authorization: Bearer kb_dein_schlüssel

Scopes

Scope	Typische Nutzung
`read`	Listen und Abruf
`write`	Anlegen und Ändern
`admin`	administrative Aktionen (wo die API es vorsieht)

Standard ist oft read + write. Integrations möglichst mit minimalem Scope planen.

Ratenbegrenzung

Bereich	Orientierungswert
Globales *`/api/`-Limit**	etwa 100 Anfragen pro Minute pro Nutzer oder Client-IP
`GET /api/health`	vom globalen Limit ausgenommen

Antwort bei Überschreitung: HTTP 429 mit JSON, u. a. retryAfterSeconds. Header: X-RateLimit-*, bei 429 zusätzlich Retry-After.

Automation: bei 429 mit exponentieller Pause erneut versuchen.

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

Ohne updatedSince enthält die Antwort typischerweise data, total, limit, offset.

Inkrementeller Sync

Query-Parameter updatedSince (ISO 8601) — nur geänderte Dokumente.
Optional format=markdown — liefert pro Eintrag markdownText (u. a. für Obsidian Selective Pull).
Hohe effektive Limits; Details im OpenAPI-Eintrag list documents.

Anfragekörper: Markdown vs. TipTap-JSON

text: Markdown — wird serverseitig in TipTap/ProseMirror-JSON umgewandelt.
content: bereits serialisiertes TipTap-JSON — für fortgeschrittene Clients.

Fehler

Beispiel:

{ "error": "Document not found" }

HTTP	Bedeutung (vereinfacht)
401	Kein/ungültiger Schlüssel
403	Kein Workspace / keine Rechte
404	Ressource fehlt
429	Rate-Limit

OpenAPI

Maschinenlesbare Spezifikation (3.1) und interaktive Oberfläche: API-Referenz →