Tesria

API reference

Every request this version of Tesria answers: 200 of them, grouped by area. It is made from the OpenAPI document your Tesria serves, each time this site is published, so it lists what exists rather than what someone remembered to write down.

Two more ways to see the same thing, on your own server:

  • https://your-server/api/docs: the interactive reference, with every request’s fields and answers, and a Test Request button to try one. It needs no account to read.

  • https://your-server/api/openapi.json: the document itself, for tools that generate a client library from an OpenAPI description.

Reading the list

  • Each line is the method and the path. {id} and the like are filled in: GET /api/pages/{id} becomes GET /api/pages/2f9a…. After it come the query parameters it takes and the fields of its JSON body, when it has any.

  • A read-only token may use any GET. Anything else needs a token with full access, and some of it needs a right on the instance or the space as well. What you may not see answers 404, exactly as if it did not exist.

  • A token cannot manage its account: API tokens, the password, sessions, two-factor and the profile answer token_not_allowed. Those are done in a browser.

  • Administration is listed for completeness. Each of those requests needs the same right as its tab in Administration.

On this page

Spaces

Spaces: list, create, read, change, archive, delete, and which exports each allows.

  • GET /api/spaces query: includeArchived

  • POST /api/spaces body: key, name, description

  • GET /api/spaces/{key}

  • PUT /api/spaces/{key} body: name, description, iconKind, iconValue, iconColor, treeStyle

  • DELETE /api/spaces/{key} body: confirmKey, password, code

  • POST /api/spaces/{key}/archive

  • GET /api/spaces/{key}/deletion-preview

  • PUT /api/spaces/{key}/exports body: markdown, html, pdf, site, pack

  • POST /api/spaces/{key}/unarchive

Pages

Pages: the tree, reading and writing, history, moving and copying, drafts and the trash.

  • POST /api/pages body: spaceId, parentPageId, title, contentJson

  • GET /api/pages/{id}

  • PUT /api/pages/{id} body: title, contentJson, changeComment, baseVersion

  • DELETE /api/pages/{id}

  • POST /api/pages/{id}/copy body: spaceId, parentPageId, includeChildren

  • DELETE /api/pages/{id}/draft

  • PUT /api/pages/{id}/emoji body: emoji

  • PUT /api/pages/{id}/layout body: fullWidth

  • PUT /api/pages/{id}/move body: parentPageId, index, spaceId

  • POST /api/pages/{id}/publish body: title, contentJson

  • DELETE /api/pages/{id}/purge

  • POST /api/pages/{id}/restore

  • GET /api/pages/{id}/versions

  • GET /api/pages/{id}/versions/{number}

  • POST /api/pages/{id}/versions/{number}/restore

  • POST /api/pages/draft body: spaceId, parentPageId

  • GET /api/pages/trash query: spaceId

  • GET /api/pages/tree query: spaceId

Full-text search across everything the caller may see.

  • GET /api/search query: q, spaceId

Labels

Labels on pages, and finding pages by label.

  • GET /api/labels

  • GET /api/labels/{name}/pages

  • GET /api/pages/{pageId}/labels

  • POST /api/pages/{pageId}/labels body: name

  • DELETE /api/pages/{pageId}/labels/{name}

Comments

Comments on a page or on a few words of it, and replies.

  • PUT /api/comments/{id} body: body

  • DELETE /api/comments/{id}

  • POST /api/comments/{id}/reopen

  • POST /api/comments/{id}/resolve

  • GET /api/pages/{pageId}/comments

  • POST /api/pages/{pageId}/comments body: body, parentCommentId, anchorJson

Attachments

Files attached to pages: upload, list, download, remove.

  • GET /api/attachments/{id}

  • DELETE /api/attachments/{id}

  • GET /api/attachments/{id}/download

  • GET /api/attachments/{id}/view

  • GET /api/pages/{pageId}/attachments

  • POST /api/pages/{pageId}/attachments body: a file (multipart form)

Templates

Page templates, for a space or the whole wiki.

  • GET /api/templates query: spaceId

  • POST /api/templates body: spaceId, name, description, contentJson

  • PUT /api/templates/{id} body: name, description

  • DELETE /api/templates/{id}

Watches

Watching a page or a space, to be notified of changes.

  • GET /api/pages/{pageId}/watch

  • POST /api/pages/{pageId}/watch

  • DELETE /api/pages/{pageId}/watch

  • GET /api/spaces/{key}/watch

  • POST /api/spaces/{key}/watch

  • DELETE /api/spaces/{key}/watch

Notifications

The bell: what the caller has been told about.

  • GET /api/notifications query: unreadOnly, take

  • POST /api/notifications/{id}/read

  • POST /api/notifications/read-all

  • GET /api/notifications/unread-count

Permissions

Who may view, edit or administer a space, and restrictions on single pages.

  • GET /api/pages/{pageId}/restrictions

  • POST /api/pages/{pageId}/restrictions body: principalType, principalId, operation

  • DELETE /api/pages/{pageId}/restrictions/{id}

  • GET /api/spaces/{key}/permissions

  • POST /api/spaces/{key}/permissions body: principalType, principalId, operation

  • DELETE /api/spaces/{key}/permissions

  • DELETE /api/spaces/{key}/permissions/{id}

Groups

Named sets of people, for sharing with a team at once.

  • GET /api/groups

  • POST /api/groups body: name, description

  • PUT /api/groups/{id} body: name, description

  • DELETE /api/groups/{id}

  • GET /api/groups/{id}/members

  • POST /api/groups/{id}/members body: userId

  • DELETE /api/groups/{id}/members/{userId}

  • GET /api/users

Export

A page as Markdown, HTML or PDF, a space as a website or a wiki pack, and importing a pack.

  • GET /api/export-progress/{id}

  • GET /api/pages/{id}/export query: format

  • GET /api/spaces/{key}/export/pack query: progress

  • GET /api/spaces/{key}/export/site query: audience, progress

  • POST /api/spaces/import

Blocks

Live content (a page’s children, recent changes and the rest), resolved for the caller.

  • GET /api/pages/{hostId}/blocks/{kind}

Embeds

Link previews and embeds, from the sites on the allowed list.

  • GET /api/embeds/resolve query: url

  • GET /api/embeds/unfurl query: url

Media

Avatars and space icons.

  • GET /api/media/avatars/{userId}

  • PUT /api/media/avatars/me body: a file (multipart form)

  • DELETE /api/media/avatars/me

  • PUT /api/media/avatars/me/variant body: variant

  • GET /api/media/space-icons/{key}

  • PUT /api/media/space-icons/{key} body: a file (multipart form)

  • DELETE /api/media/space-icons/{key}

Webhooks

Webhooks for a space: calls to your program when something happens.

  • GET /api/spaces/{key}/webhooks

  • POST /api/spaces/{key}/webhooks body: url, events

  • DELETE /api/spaces/{key}/webhooks/{id}

API tokens

The caller’s own API tokens. Only from a browser session: a token cannot manage tokens.

  • GET /api/api-tokens

  • POST /api/api-tokens body: name, readOnly, expiresInDays

  • DELETE /api/api-tokens/{id}

Auth

Signing in and out, the caller’s own account, sessions and two-factor. Only GET /api/auth/me answers a token.

  • POST /api/auth/login body: email, password

  • POST /api/auth/login/totp body: challenge, code

  • POST /api/auth/logout

  • GET /api/auth/me

  • PUT /api/auth/me body: displayName

  • PUT /api/auth/me/email body: currentPassword, email

  • PUT /api/auth/me/notifications body: emailNotifications

  • PUT /api/auth/me/onboarding body: tourCompleted, tourSkipped, tipsEnabled, dismissTip, resetTips, resetTour

  • PUT /api/auth/me/password body: currentPassword, newPassword

  • GET /api/auth/me/recovery-codes

  • POST /api/auth/me/recovery-codes body: currentPassword

  • POST /api/auth/me/recovery-codes/acknowledge

  • GET /api/auth/me/sessions

  • DELETE /api/auth/me/sessions/{id}

  • DELETE /api/auth/me/sessions/others

  • POST /api/auth/me/totp/disable body: currentPassword, code

  • POST /api/auth/me/totp/enable body: code

  • POST /api/auth/me/totp/setup body: currentPassword

  • GET /api/auth/oidc/login query: returnUrl

  • GET /api/auth/oidc/status

  • POST /api/auth/reauth body: password, code

  • POST /api/auth/recover/code body: email, code, newPassword

  • POST /api/auth/recover/email body: email

  • POST /api/auth/recover/token body: token, newPassword

  • GET /api/auth/recovery-options

  • POST /api/auth/register body: email, displayName, password, inviteToken

Collaboration

Editing at the same time: the short-lived token the editor opens a page with.

  • GET /api/pages/{id}/collab-token

Instance

What an anonymous visitor may know about this Tesria: its name, branding and version.

  • GET /api/instance

Setup

The first-run setup wizard.

  • GET /api/setup

  • POST /api/setup/complete

  • POST /api/setup/steps/{key} body: skipped

Admin

Administration: people, roles, invites, spaces, security, backups, settings, branding, API tokens and the dashboard. Each needs its own right.

  • GET /api/admin/about

  • POST /api/admin/about/check

  • GET /api/admin/about/notices

  • GET /api/admin/api-tokens

  • DELETE /api/admin/api-tokens/{id}

  • GET /api/admin/api-tokens/activity query: tokenId, take

  • GET /api/admin/api-tokens/summary query: days

  • POST /api/admin/audit/verify

  • GET /api/admin/backups query: includeRemoved

  • POST /api/admin/backups/{label}/restore body: confirmLabel, password, code, at

  • GET /api/admin/backups/{label}/restore-preview query: at

  • POST /api/admin/backups/{label}/restore-test

  • GET /api/admin/backups/jobs/{id}

  • PUT /api/admin/backups/policy body: enabled, keepCount, keepDays

  • POST /api/admin/backups/policy/preview body: enabled, keepCount, keepDays

  • POST /api/admin/backups/restore/cancel

  • POST /api/admin/backups/restore/discard-kept body: confirmLabel, password, code, at

  • POST /api/admin/backups/restore/undo body: confirmLabel, password, code, at

  • POST /api/admin/backups/run

  • POST /api/admin/backups/targets/{slot}/copy

  • POST /api/admin/backups/targets/{slot}/test

  • GET /api/admin/branding

  • PUT /api/admin/branding body: brandName, display, signInArrangement, themePolicy, accentPolicy, accentName, accentLight, accentDark

  • POST /api/admin/branding/accent-preview body: light, dark

  • PUT /api/admin/branding/favicon body: a file (multipart form)

  • DELETE /api/admin/branding/favicon

  • PUT /api/admin/branding/logo body: a file (multipart form)

  • DELETE /api/admin/branding/logo

  • PUT /api/admin/branding/logo-dark body: a file (multipart form)

  • DELETE /api/admin/branding/logo-dark

  • POST /api/admin/branding/reset

  • GET /api/admin/dashboard query: rangeDays

  • GET /api/admin/invites

  • POST /api/admin/invites body: email, expiresInDays, sendEmail, message

  • DELETE /api/admin/invites/{id}

  • GET /api/admin/invites/email

  • GET /api/admin/roles

  • POST /api/admin/roles body: name, description, tier, copyFrom

  • PUT /api/admin/roles/{roleId} body: name, description

  • DELETE /api/admin/roles/{roleId}

  • PUT /api/admin/roles/{roleId}/permissions body: permissions

  • POST /api/admin/roles/{roleId}/reset

  • POST /api/admin/roles/review

  • GET /api/admin/security/alerts query: status

  • POST /api/admin/security/alerts/{id}/acknowledge body: note

  • POST /api/admin/security/alerts/{id}/resolve body: note

  • GET /api/admin/security/blocks

  • POST /api/admin/security/blocks body: cidr, reason, expiresInHours

  • DELETE /api/admin/security/blocks/{id}

  • GET /api/admin/security/events query: kind, severity, take

  • GET /api/admin/security/limits

  • GET /api/admin/security/overview

  • GET /api/admin/settings

  • PUT /api/admin/settings body: instanceName, baseUrl, allowPublicRegistration, allowPublicSpaces, emailEnabled, smtpHost, smtpPort, smtpUsername, smtpPassword, smtpFromAddress, smtpTls, requireTotpForAdmins, embedAllowlist, loginRateLimitPerMinute, anonymousRateLimitPerMinute, tokenMintLimitPerHour, lockoutThreshold, lockoutBaseSeconds, lockoutMaxSeconds, smtpProvider, microsoftClientId, microsoftClientSecret, microsoftTenant, googleClientId, googleClientSecret, restrictImageHosts, imageAllowlist

  • POST /api/admin/settings/email/oauth/{provider}/start

  • POST /api/admin/settings/email/oauth/complete body: address

  • POST /api/admin/settings/email/oauth/disconnect

  • GET /api/admin/settings/email/providers

  • POST /api/admin/settings/email/test

  • GET /api/admin/spaces

  • PUT /api/admin/spaces/{key}/public body: isPublic, publicComments

  • POST /api/admin/spaces/{key}/recover-access

  • GET /api/admin/tailscale

  • GET /api/admin/users

  • POST /api/admin/users/{userId}/disable-two-factor

  • POST /api/admin/users/{userId}/reset-password

  • POST /api/admin/users/{userId}/revoke-sessions

  • POST /api/admin/users/{userId}/revoke-tokens

  • PUT /api/admin/users/{userId}/role body: role, roleId

  • PUT /api/admin/users/{userId}/status body: status

  • POST /api/admin/users/{userId}/transfer-ownership

  • POST /api/admin/users/{userId}/unlock

Audit

The audit log.

  • GET /api/audit query: targetType, targetId, take

Health

Whether this Tesria is running (/api/health); the version too, to a signed-in caller.

  • GET /api/health

Applies to

Tesria 0.6 and later

Updated

September 24, 2026

Changes

Revised.