Quickstart

To create an integration, you need the Bottari desktop app and the team owner role. To connect a database, you need full access to that database.

Create an integration

In the desktop app, go to Settings → API integrations → New integration, enter a name, and select Create.A new integration can only read. See Capabilities for the defaults.

Copy the token

On the integration’s page, select Copy next to Secret, then add the token to your server’s environment.

export BOTTARI_TOKEN="bti_..."

Don’t put the token in source code or in files sent to a browser. Anyone with the token can read the connected databases.

Connect a database

Under Connected databases, select Add database and choose a database.Personal databases can’t be connected. Only space databases and restricted databases can. See Connections for the full scope.

Check the integration

Call GET /v1/users/me to confirm the token works. This endpoint answers regardless of capabilities.

curl https://api.bottari.ai/notion/v1/users/me \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Notion-Version: 2026-03-11"

Every request needs the Notion-Version: 2026-03-11 header. Without it, the request is rejected with a 400.

Find the database

Search for the connected database to get its ID. Leave out query to list every database the integration can see.

curl https://api.bottari.ai/notion/v1/search \
  -X POST \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{ "filter": { "property": "object", "value": "data_source" } }'

Read rows

Query the database with that ID. Without a sort, the most recently created rows come first.

curl https://api.bottari.ai/notion/v1/data_sources/exampleDb001/query \
  -X POST \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{ "page_size": 10 }'

Write a row (optional)

Write capabilities start off. Under Capabilities, turn on Update content to update rows and Insert content to create them.

curl https://api.bottari.ai/notion/v1/pages/exampleRow01 \
  -X PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{ "properties": { "Done": { "checkbox": true } } }'

Common first errors

Response	Cause	Fix
401 `unauthorized`	The token is missing or wrong.	Check the `Authorization: Bearer <token>` header. A regenerated secret invalidates the old token right away.
400 `missing_version`	The `Notion-Version` header is missing.	Send `Notion-Version: 2026-03-11`.
400 `validation_error` with `Notion-Version ... is not supported`	You sent a different version.	Send `Notion-Version: 2026-03-11`.
403 `restricted_resource`	The capability is off.	Check Capabilities.
404 `object_not_found`	The ID doesn’t exist or the database isn’t connected.	Check the ID and the connection.

See Common rules for every error code.

Get started

Import data

Authentication and access

Limits

Webhooks

Common first errors

​Common first errors

Common first errors