> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bottari.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create an integration, connect a database, and send your first request.

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.

**1. 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](https://developers.bottari.ai/auth/capabilities.md) for the defaults.

**2. Copy the token**

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

```bash theme={null}
export BOTTARI_TOKEN="bti_..."
```

> [!WARNING]
>
> Don't put the token in source code or in files sent to a browser. Anyone with the token can read the connected databases.

**3. 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](https://developers.bottari.ai/auth/connections.md) for the full scope.

**4. Check the integration**

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

```bash theme={null}
curl https://api.bottari.ai/v1/users/me \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11"
```

> [!NOTE]
>
> The `Bottari-Version: 2026-03-11` header is optional. Without it, the request uses the current version.

**5. Find the database**

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

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

**6. Read rows**

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

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

**7. Write a row (optional)**

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

```bash theme={null}
curl https://api.bottari.ai/v1/pages/exampleRow01 \
  -X PATCH \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-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 `validation_error` with `Bottari-Version ... is not supported` | You sent a different version. | Send `Bottari-Version: 2026-03-11`, or leave the header out. |
| 403 `restricted_resource` | The capability is off. | Check [Capabilities](https://developers.bottari.ai/auth/capabilities.md). |
| 404 `object_not_found` | The ID doesn't exist or the database isn't connected. | Check the ID and the connection. |

See [Common rules](https://developers.bottari.ai/api-reference/overview.md#errors) for every error code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.