Connections

An integration can only read and write the databases connected to it. You connect one database at a time. There’s no way to connect a whole space at once.

Connect a database

You can connect a database in two places:

On the integration’s page: Connected databases → Add database
In the database’s ⋯ menu: API integrations

Task	Who can do it
Create an integration, manage its token and capabilities, delete it, manage its webhook	Team owners
Connect or disconnect a database	Team members with full access to that database. Guests can’t.

Which databases can connect

Space databases and restricted databases can connect. These can’t:

Personal databases
Session lists and conversation archives
System databases
Databases with no owner

Inline databases don’t connect on their own. They become visible when the database holding their document is connected.

What a connection opens

The database’s rows
Subpages under those rows
Inline databases inside those rows and subpages, and their rows

What stays hidden

Object	Behavior
Rows with their own access settings	The row, its subpages, and inline databases inside it look like they don’t exist. Reading one directly returns 404.
Another database shown through a linked view in the content	The view doesn’t open it. Connect that database separately.
A relation property pointing at a database that isn’t connected	Left out of the data source’s `properties`. In rows it stays as `relation: []` and `has_more: false`. Rollups that use it are empty.
A mention of a document the integration can’t read	Has the ID, and `plain_text` is `Untitled`.
A card pointing at a document the integration can’t read	`unsupported` block with `block_type: "alias"`.

Relation filters match the real relations even when the target database is hidden. Rollup filters and sorts use the empty value. Formula and rollup values are computed only from rows the integration can see.

Response for a database that isn’t connected

A resource that isn’t connected can’t be told apart from one that doesn’t exist. Both return 404 object_not_found.

{
  "object": "error",
  "status": 404,
  "code": "object_not_found",
  "message": "Could not find data source with ID: exampleDb001. Make sure the relevant pages and databases are shared with your connection \"Order sync\".",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

Disconnect a database

Selecting Disconnect on the integration’s page makes that database return 404 immediately. Webhooks stop immediately too, and events waiting to be sent are dropped. No event announces the disconnection.

Trashed databases

A connected database stays connected when it moves to the trash. Until you disconnect it, the integration reads it like this:

Request	Response
Read the database, data source, or block	200 with `in_trash: true`
Read a row, property, or Markdown	200. The row object has `in_trash: true`.
Query, or read block children	404
Search	Not in the results.
Create or update a row	400 `Can't edit block that is archived...`

The integration’s page marks the connection as In trash, and you can disconnect it there.

Get started

Import data

Authentication and access

Limits

Webhooks

Connect a database

Which databases can connect

What a connection opens

What stays hidden

Response for a database that isn’t connected

Disconnect a database

Trashed databases

​Connect a database

​Which databases can connect

​What a connection opens

​What stays hidden

​Response for a database that isn’t connected

​Disconnect a database

​Trashed databases

Connect a database

Which databases can connect

What a connection opens

What stays hidden

Response for a database that isn’t connected

Disconnect a database

Trashed databases