API & personal access tokens

tela has a JSON REST API under /api, plus a built-in MCP server so agents are first-class.

Authentication

Session cookie (tela_session) — the browser app.
Bearer token — Authorization: Bearer tela_pat_…. Checked before the cookie; an invalid bearer is a hard 401 (no cookie fallback).

Personal access tokens (PATs)

Every user creates and manages their own tokens in Settings → API Keys. Reach for one to [[Sync your vault (WebDAV)|sync a space to a local folder]], script against the REST API, or connect an agent on a host without OAuth. The raw token (tela_pat_…) is shown once — store it safely; tela keeps only an HMAC.

Each token carries a scope (a ceiling, not a floor):

Scope	Grants
`read`	Read-only — GETs on pages, spaces, search
`write`	Read + create/edit pages and comments, imports
`admin`	Full instance admin — instance admins only

A token can be pinned to a single space (clamps everything, incl. search and "ask", to that space), carry an expiry, and be revoked anytime.

The API surface (orientation)

The full, machine-readable description lives at {your-instance}/openapi.json — an OpenAPI 3.1 document you can point Scalar, Swagger UI, Postman, or an agent at. On the hosted instance: https://telawiki.com/openapi.json.

[!NOTE] The REST API is internal. It powers tela's own frontend, carries no version prefix, and can change between releases. The stable integration surface is the MCP server; GET /api/health and GET /api/version are the only REST routes with a stability promise. Build against MCP where you can, and read the OpenAPI document when you need the exact HTTP shape.

Errors: { "error": "...", "code": "..." } — e.g. unauthorized, forbidden, not_found, conflict, quota_exceeded, rate_limited, api_key_scope.
Pages: GET/POST /api/pages, GET/PATCH/DELETE /api/pages/{id} (body is canonical markdown); history /api/pages/{id}/revisions, backlinks /api/pages/{id}/backlinks.
Spaces & orgs: /api/spaces, /api/orgs, share-grant routes.
Search: /api/search (keyword); semantic /api/rag/search, /api/rag/ask.
Meta: GET /api/version, GET /api/health (public).

MCP

Agents connect to {your-instance}/api/mcp (Streamable HTTP). Most clients — Claude, ChatGPT, Cursor, Claude Code — authenticate via OAuth with no token at all; a PAT as the bearer token also works (and is needed for the stdio proxy). Full client setup in [[Agents & MCP]].