V2
Scope Reference
Review V2 scopes and how endpoint permissions map to them.
Scope Reference
Scopes control what a token can do. The token must have every scope required by an endpoint.
Scopes
| Scope | Description |
|---|---|
pages.read |
Read page metadata and properties. |
pages.write |
Create, update, move, and soft-delete pages; create or edit mind maps; upload files for page workflows. |
blocks.read |
Read blocks and block children. |
blocks.write |
Append, update, and soft-delete blocks. |
databases.read |
Read databases and query records. |
databases.write |
Create, update, and soft-delete databases; mutate records and manage views. |
users.read |
Read user profiles. |
users.email.read |
Return user email addresses in person.email. |
search.read |
Run keyword and semantic search. |
Endpoint to Scope Mapping
| Endpoint | Scope |
|---|---|
GET /v2/users/me |
No additional scope. |
GET /v2/users/:user_id |
users.read; users.email.read controls email visibility. |
GET /v2/users |
users.read; requires a workspace-scoped credential. |
POST /v2/search |
search.read |
POST /v2/search/semantic |
search.read |
GET /v2/pages |
pages.read |
GET /v2/pages/:page_id |
pages.read |
GET /v2/pages/:page_id/properties/:property_id |
pages.read |
POST /v2/pages |
pages.write |
PATCH /v2/pages/:page_id |
pages.write |
PATCH /v2/pages/:page_id/move |
pages.write |
DELETE /v2/pages/:page_id |
pages.write |
GET /v2/blocks/:block_id |
blocks.read |
GET /v2/blocks/:block_id/children |
blocks.read |
PATCH /v2/blocks/:block_id/children |
blocks.write |
PATCH /v2/blocks/:block_id |
blocks.write |
DELETE /v2/blocks/:block_id |
blocks.write |
GET /v2/databases/:database_id |
databases.read |
POST /v2/databases/:database_id/query |
databases.read |
POST /v2/databases |
databases.write |
PATCH /v2/databases/:database_id |
databases.write |
DELETE /v2/databases/:database_id |
databases.write |
POST /v2/databases/:database_id/mutations |
databases.write + pages.write |
GET /v2/databases/:database_id/views |
databases.read |
GET /v2/databases/:database_id/views/:view_id |
databases.read |
POST /v2/databases/:database_id/views |
databases.write |
PATCH /v2/databases/:database_id/views/:view_id |
databases.write |
DELETE /v2/databases/:database_id/views/:view_id |
databases.write |
GET /v2/workspace |
Authenticated token; no additional scope. |
GET /v2/workspace/pages |
pages.read; requires a workspace-scoped credential. |
GET /v2/workspace/pages/:section |
pages.read; requires a workspace-scoped credential. |
POST /v2/mind-maps |
pages.write |
GET /v2/mind-maps/:mind_map_id |
pages.read |
PATCH /v2/mind-maps/:mind_map_id |
pages.write |
GET /v2/pages/:page_id/content/markdown |
pages.read + blocks.read |
POST /v2/files/upload-url |
pages.write |
GET /v2/files/download-url |
blocks.read |
Notes
- A token can have more scopes than an endpoint requires.
- Missing scopes return
403 forbidden. - Resource access is checked separately from scopes.
- Email visibility requires
users.email.readin addition tousers.read. GET /v2/openapi.jsonandGET /v2/openapi/metaare public and require no token.- Soft-delete endpoints are documented HTTP capabilities but are intentionally absent from the machine-readable OpenAPI document.