Capabilities

Set capabilities under Capabilities on the integration’s page. Only team owners can change them. Changes save immediately and apply from the next request.

In the app	Value	Default	What it allows
Read content	`read_content`	On (can’t be turned off)	Search, databases, data sources, queries, pages, properties, Markdown, blocks
Update content	`update_content`	Off	`PATCH /v1/pages/{id}`: update properties, trash, restore, archive, lock, icon, cover
Insert content	`insert_content`	Off	`POST /v1/pages`: create rows
Read comments	`read_comments`	Off	`GET /v1/comments`, `GET /v1/comments/{id}`, `comment.*` webhook events
User information	`user_info`	Without email (`no_email`)	How much personal information responses include. See below.

If a required capability is off, the response is 403.

{
  "object": "error",
  "status": 403,
  "code": "restricted_resource",
  "message": "Insufficient permissions for this endpoint.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

GET /v1/users/me answers regardless of capabilities.

Scope of write capabilities

Update content and Insert content are separate. An integration with only Insert content can create rows but not update them.
Writing a new name to a select or multi_select property creates the option under the capability that write uses.
An integration can write the rows it can read. See Connections.
An integration can write to locked rows and locked databases.
An integration can’t write to a database with a task agent attached. The response is 403.
Integration writes also run database automations. An automation runs with its creator’s permissions.

User information

Value	In the app	User object	`GET /v1/users`, `/v1/users/{id}`
`none`	None	`object` and `id` only	403
`no_email`	Without email	Adds name and avatar	200
`email`	With email	Adds `person.email` and `person.email_verified`	200

The value also affects these:

Where	`none`	`no_email`	`email`
`plain_text` of a person mention	`@Anonymous`	`@Name`	`@Name`
Formula `name()`	Empty text	Name	Name
Formula `email()`	Empty text	Email	Email
Writing a person to a people property	404	200	200
`people.contains` filter	Works	Works	Works

Formula email() returns the email address even with Without email. User objects have no email, but a database with such a formula property exposes it.

Bots always show their name, regardless of this value. A bot object is { "object": "user", "id": "...", "name": "...", "avatar_url": null, "type": "bot", "bot": {} }. With none, a people property only accepts bots and empty values. Sending a person who is already in the property still returns 404. With none, a formula that converts a list of people to text has empty names, and map in a formula keeps those people.

Get started

Import data

Authentication and access

Limits

Webhooks

Scope of write capabilities

User information

​Scope of write capabilities

​User information

Scope of write capabilities

User information