REST API overview

The REST API under /api/v1/ lets integrations and tools (including the Obsidian plugin) manage documents and collections with a stable JSON interface. This page explains behavior that applies to all endpoints. Per-operation fields and request bodies are documented in the OpenAPI reference.

Base URL

Use the same origin as your deployed Orimora instance:

Production: https://your-domain.example.com
Local (Vite): http://localhost:5173
Docker Compose (app service): http://localhost:3000 unless you remap the port

All paths in this document are relative to that base (e.g. GET /api/v1/documents).

Authentication

API keys (Bearer)

In the web app, go to Settings → Developers and create an API key.
Keys are shown once and have the prefix kb_.
Send the key as a Bearer token:

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

The server resolves the key to a user and team. Routes that use requireUser() accept either a normal browser session or this Bearer token.

Scopes

Each key has one or more scopes:

Scope	Typical use
`read`	List and fetch documents and collections
`write`	Create and update resources
`admin`	Operations that change team-level settings (when exposed)

Default for new keys is read + write. Design integrations so they use the smallest scope necessary.

Rate limiting

Area	Limit (indicative)	Notes
*All `/api/` routes**	100 requests per IP or user per 60 seconds	Global guard in the request pipeline; skipped for `GET /api/health`
Auth endpoints	Stricter (e.g. magic link / OAuth)	Protects against abuse; see implementation for exact keys

When limited, the response is 429 Too Many Requests with JSON similar to:

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

Successful responses may include:

X-RateLimit-Limit — max requests per window
X-RateLimit-Remaining — remaining in current window
Retry-After — present on 429

Treat 429 with exponential backoff in automation.

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

Without updatedSince, list responses include:

Field	Meaning
`data`	Array of documents
`total`	Total rows matching filters (not just this page)
`limit`	Page size (capped, default 25, max 100)
`offset`	Skip offset

Filter the list with these query parameters:

Parameter	Meaning
`collectionId`	Limit to one collection
`parentDocumentId`	Limit to direct children of a document
`title`	Exact title match, case-insensitive — for targeted existence lookups (used by the plugin)
`status`	`published` or `draft`
`tag`	Filter to documents carrying this tag (by name, case-insensitive). Repeat the param (`?tag=a&tag=b`) for a multi-tag AND filter — only documents carrying all listed tags match
`limit` / `offset`	Page size (default 25, max 100) and skip offset

Incremental sync (`updatedSince`)

For tools that only need changed documents since a point in time:

Pass updatedSince as an ISO 8601 timestamp (e.g. 2026-04-01T12:00:00.000Z).
The response shape differs: there is no total/offset pagination in the same way; the server uses a higher effective limit for the sync window.
Add format=markdown together with updatedSince to receive a markdownText field per document for plain-text sync (used by the Obsidian selective pull).

See the OpenAPI /api/v1/documents GET operation for details.

Request bodies: Markdown vs TipTap JSON

text: Markdown string — the server converts it to TipTap/ProseMirror JSON internally.
content: Raw TipTap JSON if you already have structured content (advanced integrations).

You typically use one or the other, not both, when creating or updating body content.

Responses and errors

Success payloads usually look like:

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

List endpoints return { "data": [ … ] } plus pagination fields as documented per route.

Errors use JSON with an error string (and HTTP 4xx/5xx):

{ "error": "Document not found" }

HTTP	Typical cause
401	Missing or invalid API key / session
403	Authenticated but not allowed (e.g. onboarding incomplete)
404	Resource not found or wrong team
429	Rate limited
400	Validation / bad JSON

Webhooks

Document lifecycle events can trigger webhooks configured in the workspace. Webhook delivery, signing, and retries are not part of the /api/v1/ CRUD surface; configure them in the app UI. Automation should still use idempotent handlers and verify signatures when provided.

OpenAPI

The same operations are available as OpenAPI 3.1 for code generators and the Starlight UI:

Interactive API reference →

Regenerate the bundled spec with:

cd docs && yarn generate:openapi

(Runs automatically as part of yarn build in the docs package.)