Every API request is authorized by checking the scopes granted to the bearer token (user session token or API token). This page is the complete reference for the permission scopes.
When creating API tokens via the web UI, CLI or API, only the following scopes can be assigned:
Scope
Use case
documents:read
Read documents and their content
documents:write
Create and update documents
documents:delete
Delete documents
ingest:write
Trigger document ingestion/parsing
chunks:read
Read document chunks
chunks:write
Create and update document chunks
graph:read
Read graph objects
graph:write
Create and update graph objects
graph:search:read
Graph-specific vector search
search
Run hybrid and semantic search (MCP)
search:read
Unified REST search (vector + keyword)
journal:read
Read the project journal
journal:write
Append to the project journal
extraction:read
View extraction jobs, logs and statistics
extraction:write
Create, cancel and retry extraction jobs
tasks:read
List and read tasks
tasks:write
Resolve and cancel tasks
notifications:read
List and read notifications
notifications:write
Mark notifications as read
user-activity:read
View the user activity log
user-activity:write
Write user activity entries
schema:read
Read-only access to type registry and template packs
schema:write
Install and modify schemas (also grants schema:migrate)
branches:read
List and inspect graph branches
branches:write
Create, merge and delete graph branches
agents:read
Use chat and view agent runs
agents:write
Create and manage agents, trigger runs
skills:read
Read project skills
skills:write
Create and manage project skills
projects:read
List and read projects
projects:write
Create and manage projects
project:admin
Full project admin for one project (project-bound tokens only, minted by a project admin)
admin, admin:all
Platform admin (requires an active superadmin_full)
The retired data:read / data:write umbrellas are not assignable. Fine-grained internal scopes (e.g. org:read, admin:write) and the reserved marker scopes (device:api, webhook:trigger, mcp:agent-call, share:agent-chat) cannot be assigned to user-created API tokens either.