Guides
What an endpoint signature cannot tell you: getting a token, the scopes each endpoint needs, and the conventions every request shares.
The API reference describes each endpoint’s request and response. These guides cover what a signature cannot tell you: how to get a token, which scopes an endpoint needs, and the conventions every endpoint shares.
They assume you already have access to a workspace.
| Guide | What it answers |
|---|---|
| Connect a client | Registering a client, the PKCE flow, and refreshing a token |
| Scopes and consent | Which scopes an endpoint needs, and the four checks a request passes |
| Conventions | Idempotency, pagination, revisions, request limits |
| Errors | The refusal format, and which refusals are worth retrying |
| Public endpoints | The form boundary and the Meta webhook, which are not this API |
What is not here
The signed-in workspace transport, every path under /api/v1/workspace, is not part of this API. It accepts the web application’s own session and refuses a bearer token with 403 and the reason workspace_session_required.
That is deliberate rather than an omission. Those routes map onto coarse actions — records.write there also edits organization settings and the access-control policy — and a permission that broad cannot be delegated to a third party at consent. External clients get the documented REST resources and MCP.