Basalt docs
basaltapp.io

API reference

Every operation Basalt calls under /api/v1 — 193 of them across 146 paths, generated from the OpenAPI 3.1.0 document the server emits from its own route table. If an endpoint is documented here, it exists.

One server answers more than one product, and this reference covers the areas this one uses. An endpoint absent from these pages is not necessarily absent from the server — it belongs to a surface you have not been given.

Start with API for authentication, error shapes, pagination and webhooks.

Workspaces and people

Workspaces, their members, groups and invitations, the capabilities of the calling account, and what the workspace has used of its plan.

Collections

The top level of the page tree, and who may see each one.

Pages

Creating, moving, trashing and restoring pages; their Markdown surface, field values, relations, backlinks, search, and the pages a person pins.

Databases and fields

The workspace field registry, databases and their bound fields, saved views, and row memberships.

Collaboration

Comments, page history, activity, notifications, attachments and the workspace symbol library.

Permissions and sharing

Per-page access control lists, restriction boundaries, public share links, and the token routes a stranger reads them through.

Automation

Personal access tokens, webhooks, export, and link unfurling — the operations where the instance talks to the outside world. Plus the few that run the other way: the early-access signup and the sign-in screen’s question about which ways in this deployment has, the parts of this API a caller reaches with no session at all.

Connected accounts

A person’s own authorisation at a foreign service — Google, Microsoft, a CalDAV server or a plain ICS subscription — and the calendar mirror it feeds. Personal, not workspace-shared: these routes answer with the calling account’s connections and nobody else’s, so a workspace admin sees their own and no colleague’s. Two routes change a meeting at the provider, and only on a calendar switched on for it; everything else here reads. No route returns a credential: a refresh token, an app-specific password and a subscription URL all stay on the server, and a subscription URL is treated as the bearer secret it is.

Import

Bringing a Notion export, a Confluence space or a folder of Markdown into a collection, and the read-only connections that keep doing it.

Billing and invoices

The workspace’s subscription and billing details, and the invoices this instance issues in the operator’s own number range — plus the payment provider’s callback.

Feedback

Filing a bug report or an idea from inside the app. Authenticated, and deliberately outside /workspaces/{workspaceId}: the report is addressed to the people who run the instance rather than to a workspace, which is also why it is session-only and why the workspace it names carries no authority. It travels with the screen it was written on, the build, the window, the pointer and a structural recording of what the app did — never with anything anybody wrote. Operators read them through the back office.

Instance administration

The operator back office: every workspace on this instance with its metadata and plan, the plan assignment, the append-only trail of operator actions, and the inbox of reports people have sent (see Feedback). Metadata only, with that one exception — the operator of a hosted instance is a data processor, so these routes cannot return page titles, page contents or comments, and a report is readable here only because somebody wrote and sent it to the operator. Session-only, and restricted to the operators named in OPERATORS.