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

# Dropbox

> Connect a Dropbox account over OAuth and index the folders you pick into a dataset of its own.

Connect one **Dropbox account** to Cognee through a per-user OAuth consent, pick the folders you want covered, and have their text, Markdown, CSV, PDF and Paper files become searchable memory in a dataset of that account's own.

> [!NOTE]
>
> This integration is for self-hosted Cognee deployments — you create and own the Dropbox app, so it talks only to your own Cognee backend. To sync a folder from a script instead, see [From your own script](#from-your-own-script).

## What It Does

* **One Dropbox account, one Cognee user.** The connection is keyed on the account's stable Dropbox id (`dbid:...`); the email is only a label. The account's files are indexed into the memory of the Cognee user who connected it.
* **Read-only.** The requested scopes are `files.metadata.read files.content.read account_info.read` — Cognee never writes to Dropbox.
* **Folders are picked by id, not path.** A renamed or moved folder keeps its documents, and nothing is extracted again.
* **Only supported file types are read.** Text, Markdown, CSV and PDF files and Paper docs become memory; everything else is skipped and counted. See [What gets indexed](#what-gets-indexed).
* **Incremental after the first pass.** The first sync lists each selected folder in full and keeps a Dropbox cursor; later syncs read only what changed, including deletions and moves.
* **No extra to install.** The connector uses its own `httpx` client and `pypdf`, both core dependencies.

## Prerequisites

* Cognee `v1.6.9` or later.
* A Dropbox account you can create an app with at [dropbox.com/developers/apps](https://www.dropbox.com/developers/apps).
* A backend URL Dropbox can redirect a browser to. Dropbox only redirects the user's browser, so `http://localhost:8000` works for local development.

## Setup

### 1. Create the Dropbox app

In the [Dropbox App Console](https://www.dropbox.com/developers/apps), create an app, then:

| Setting | Value |
| - | - |
| **Permissions** | Enable `files.metadata.read`, `files.content.read` and `account_info.read`. |
| **OAuth 2 → Redirect URIs** | `https://<your-host>/api/v1/integrations/dropbox/callback` — must match `DROPBOX_REDIRECT_URI` verbatim. |

Then collect the app's **App key** and **App secret**.

### 2. Configure Cognee

Add these to your backend's `.env` (the same block is in `.env.template`):

| Variable | Value |
| - | - |
| `DROPBOX_CLIENT_ID` | The app key. |
| `DROPBOX_CLIENT_SECRET` | The app secret. |
| `DROPBOX_STATE_SECRET` | Listed in `.env.template`, but nothing reads it: the OAuth `state` is signed with a key derived from `INTEGRATION_CREDENTIALS_KEY(S)`. |
| `DROPBOX_REDIRECT_URI` | The redirect URI registered on the app, e.g. `http://localhost:8000/api/v1/integrations/dropbox/callback`. |
| `DROPBOX_FRONTEND_BASE_URL` | Your frontend's origin, e.g. `http://localhost:3000` — where the callback sends the browser when the install finishes. |
| `DROPBOX_MAX_FILE_SIZE_MB` | Optional. Files larger than this are skipped, never truncated. Unset or blank means `50`. Any positive number raises or lowers it; any other value (`0`, a negative number, `inf`, text) **stops the server at startup**. |
| `INTEGRATION_CREDENTIALS_KEY` | Not Dropbox-specific — the key the integrations framework encrypts stored credentials under and derives the OAuth `state` signing key from (32 raw bytes, base64-encoded; `openssl rand -base64 32`). Without it, `/authorize` answers 503. `INTEGRATION_CREDENTIALS_KEYS` is the rotation-capable form. |

The OAuth values are checked when they are used, not at boot: a deployment without Dropbox configured starts normally, and the first call that needs a missing value fails (a 503 from `/authorize`, or from the callback for `DROPBOX_FRONTEND_BASE_URL`) with the missing variable named in the backend log. `DROPBOX_MAX_FILE_SIZE_MB` is the exception — an invalid value fails fast at startup instead of syncing with a limit nobody chose.

Restart the backend after any `.env` change.

### 3. Connect

```bash theme={null}
# Mint the authorize URL (authenticated as the Cognee user who will own the data)
curl -X POST https://<your-host>/api/v1/integrations/dropbox/authorize \
  -H "Authorization: Bearer <your-cognee-token>"
# {"authorizeUrl":"https://www.dropbox.com/oauth2/authorize?...&token_access_type=offline&..."}
```

The authorize URL carries `token_access_type=offline`, so Dropbox issues a refresh token next to the short-lived access token. As with the other OAuth connectors, the install has to be finished in the browser that called `/authorize`, within 10 minutes.

Approve the consent screen and Dropbox redirects to `/api/v1/integrations/dropbox/callback`, which binds the account to your Cognee user and sends the browser to `<DROPBOX_FRONTEND_BASE_URL>/integrations?dropbox=<outcome>`:

| Outcome | Meaning |
| - | - |
| `connected` | The account is bound. Nothing is indexed yet — see [Choosing what to index](#choosing-what-to-index). |
| `cancelled` | The consent screen was cancelled, or Dropbox rejected the request. Nothing was stored. |
| `error_invalid_state` | The state was missing, tampered with, expired, or the install cookie did not match. |
| `error_already_connected` | This Dropbox account is already connected to a different Cognee user. Disconnect it there first. |
| `error_exchange_failed` | The token exchange or account lookup failed. The traceback is in the backend log. |

## Choosing What to Index

**A fresh connection selects nothing**, and **there is no "select all"**: a whole Dropbox would cost LLM tokens to extract, so you pick folders explicitly. Reconnecting an account that already has a selection keeps it.

List the folders one level at a time:

```bash theme={null}
# Top level of the account
curl https://<your-host>/api/v1/integrations/dropbox/resources \
  -H "Authorization: Bearer <your-cognee-token>"

# Folders directly inside one folder
curl "https://<your-host>/api/v1/integrations/dropbox/resources?parent=id:a4ayc_80_OEAAAAAAAAAXw" \
  -H "Authorization: Bearer <your-cognee-token>"
```

Each entry's `id` is a Dropbox folder id (`id:...`) and its `name` is the folder's path. A `parent` that is not a folder id (a path, for example) is a **422**; one Dropbox cannot find, or a file, is a **404**.

Then save a selection:

```bash theme={null}
curl -X PUT https://<your-host>/api/v1/integrations/dropbox/resources \
  -H "Authorization: Bearer <your-cognee-token>" \
  -H "Content-Type: application/json" \
  -d '{"resourceIds": ["id:a4ayc_80_OEAAAAAAAAAXw"]}'
```

Each selected folder is read **recursively**. `resourceIds` must be a list of folder ids; `[]` selects nothing. A changed selection starts a sync at once.

The selection is checked with Dropbox **before it is stored**. When the check fails, nothing is saved:

| Status | Cause |
| - | - |
| **422** | `null` (`dropbox needs an explicit list of resource ids; null is not supported`), an id that is not `id:...` (`Not a dropbox resource id: ...`), a folder Dropbox cannot resolve (`A selected Dropbox folder could not be found; pick it again from the list`), or a folder inside another selected folder (`A selected Dropbox folder is inside another selected folder` — its files would be two documents). |
| **404** | `dropbox is not connected` — the connection is no longer active. |
| **503** | Outbound HTTP is disabled on the server (`ALLOW_HTTP_REQUESTS`). |
| **502** | `Could not check the dropbox selection; try again` — Dropbox refused the token, could not be reached, or answered with an error. The cause is in the backend log. |

> [!WARNING]
>
> **Narrowing a selection deletes data.** After the next sync, the documents of folders you dropped from `resourceIds` are removed from the dataset. Setting `resourceIds` to `[]` removes everything the account has indexed. A folder that failed in a way that may have stored nothing of its own (a listing error, an account mismatch) holds this cleanup back for that run.

## Syncing and Status

Connecting does **not** start a sync. Start one by saving a changed selection, by calling `/sync`, or with a [sync policy](https://docs.cognee.ai/integrations/google-drive-integration.md#syncing-on-a-schedule):

```bash theme={null}
curl -X POST https://<your-host>/api/v1/integrations/dropbox/sync \
  -H "Authorization: Bearer <your-cognee-token>"
# {"accepted": true}
```

The sync runs detached and fans out over the selected folders, one source per folder, each ingested through [`remember()`](https://docs.cognee.ai/python-api/remember).

* **Only the first sync reads everything.** Later syncs read the folder's changes from the cursor. A reset or rejected cursor, or a renamed selected folder, makes the next sync list that folder in full again.
* **Deletions and moves.** A file deleted at Dropbox or moved out of a selected folder is forgotten. A move within a folder is an update, not a delete. A file moved between two selected folders is extracted once more.
* **A selected folder that is gone** (deleted, or access to a shared folder lost) has its files forgotten, and later syncs count it in `failed_folder_gone` while it stays selected. If the folder comes back, it is synced from scratch.
* **Failed downloads are retried** on every sync until they succeed or Dropbox reports the file changed or gone. The stored text is kept meanwhile, and each pending file counts in `failed_retry`.

Files land in **one dataset per connected account**, named `dropbox_<email-slug>_<hash>` — the same naming rule as [Google Drive](https://docs.cognee.ai/integrations/google-drive-integration.md#syncing-and-status), with the `dropbox` prefix and a hash of the Dropbox account id.

```python theme={null}
import cognee

results = await cognee.recall(
    "What did I decide about the Q4 plan?",
    datasets=["dropbox_jane_example_com_3f2a1b9c4d"],
)
```

### What gets indexed

| Dropbox file | How it is read |
| - | - |
| `.txt`, `.md`, `.markdown`, `.csv` | As text (UTF-8, or UTF-16 with a BOM). A file with NUL bytes is treated as binary and skipped. |
| `.pdf` | Text extracted with `pypdf`. A PDF `pypdf` cannot read is skipped and not retried until it changes. |
| Paper docs | Exported as Markdown. |
| Everything else | **Skipped** and counted in `skipped_unsupported_type` — Office files, images and web links included. |

Each document's title is the file name, and its text starts with a `Modified: YYYY-MM-DD` line (the day the file's content last changed), so "what changed in March" is findable. The file's folders, up to the selected folder, are kept as its structure, so the graph shows the folder tree.

Files over `DROPBOX_MAX_FILE_SIZE_MB` (default 50) are skipped and counted in `skipped_too_large`. **A stored file that stops yielding content is forgotten** — it grew past the limit, was emptied, renamed to an unsupported type, or Dropbox refuses to serve it.

### Reading the connection state

`GET /api/v1/integrations/dropbox/connection` returns the same fields as the other OAuth connectors (see [Google Drive](https://docs.cognee.ai/integrations/google-drive-integration.md#reading-the-connection-state)); `providerAccountId` is the account's `dbid:...` id. `syncStatus` is `degraded` whenever any count under `failed` is above zero.

`syncCounts` holds counts only, never a file name:

| Key | Meaning |
| - | - |
| `scanned`, `unchanged`, `deleted` | Files read, files skipped because their content had not changed, files forgotten. |
| `skipped_too_large`, `skipped_unsupported_type`, `skipped_unparseable`, `skipped_empty_content`, `skipped_not_found`, `skipped_restricted` | Why files were skipped. |
| `failed_auth` | Dropbox refused the token, or the refresh token was revoked. Reconnect. |
| `failed_account` | The token belongs to a different Dropbox account than the connection. Reconnecting the same account will not fix it. |
| `failed_rate_limit` | Dropbox kept answering 429 after retries. The next sync resumes. |
| `failed_budget` | The sync stopped after 15 minutes of work on files. What was stored is kept and the next sync continues. |
| `failed_listing` | A selected folder could not be resolved or listed. |
| `failed_folder_not_found` | A selected folder that was never listed cannot be found. Nothing is deleted; pick the folder again. |
| `failed_folder_gone` | A selected folder that was synced before is gone, and its files were forgotten. |
| `failed_retry` | One per file still waiting for a retried download. |
| `failed_ingestion` | Any other failure of a folder. |
| `team_space_unsupported` | `1` when the account is in a Dropbox team space; see [Limitations](#limitations). |

## Token Lifecycle

Dropbox access tokens last about four hours. The connector renews the token **before a request when it is within five minutes of expiry**, and once more if Dropbox answers 401, so a long first sync does not expire halfway through. Dropbox does not rotate the refresh token, so the stored one is kept.

If Dropbox answers a refresh with `invalid_grant`, the account removed the app on Dropbox's side. Cognee revokes the local connection too, logs `Dropbox access for account <id> was revoked at the provider`, and stops the sync as `failed_auth`, keeping what was already stored. Reconnect to fix it.

## Disconnect

```bash theme={null}
# Revoke the connection, keep the indexed data
curl -X DELETE "https://<your-host>/api/v1/integrations/dropbox/connection" \
  -H "Authorization: Bearer <your-cognee-token>"

# Revoke it and forget the account's dataset as well
curl -X DELETE "https://<your-host>/api/v1/integrations/dropbox/connection?delete_data=true" \
  -H "Authorization: Bearer <your-cognee-token>"
```

Disconnecting revokes the stored credential locally, which cuts access, and **best-effort** revokes the token at Dropbox. If that remote revoke fails, the app stays listed in the account's Dropbox settings until the user removes it.

## From Your Own Script

The connector also works from the SDK with an access token, without the OAuth flow. Generate a token on your Dropbox app's settings page (it lasts about four hours), then:

```python theme={null}
import asyncio
import os

import cognee
from cognee.tasks.ingestion.connectors import dropbox_account_id, dropbox_source


async def main():
    token = os.environ["DROPBOX_ACCESS_TOKEN"]
    source = dropbox_source(
        folder_id=os.environ.get("DROPBOX_FOLDER_ID", ""),  # "id:..." or "" for the whole Dropbox
        account_id=dropbox_account_id(token),  # binds the sync state to this account
        token=token,
        resource_name="dropbox_notes",  # required: one per folder and account
    )
    await cognee.remember(
        source,
        dataset_name="my_dropbox",
        primary_key="id",
        write_disposition="merge",
        max_rows_per_table=0,
    )
    print("Sync counts:", source.cognee_sync_stats)


asyncio.run(main())
```

* `folder_id` is a folder id (`id:...`, the `id` that Dropbox's `/2/files/get_metadata` returns for a path) or `""`. A path such as `/Notes` is refused.
* `resource_name` names the staging table and the cursor. It must start with `dropbox_` and hold only lowercase letters, digits and single underscores (at most 63 characters), or `dropbox_source()` raises `ValueError`. Use one name per folder; several folders are several sources. One source sees one folder, so a script that syncs several must not pick a folder inside another.
* `token` is a string or a callable that returns a fresh token. In a script there is no file size limit unless you pass `max_file_size_mb`.
* A normal return is not proof of a finished sync: check `source.cognee_sync_stats` (`failed == 0` and `complete == 1`).

A runnable version is in [`examples/guides/dropbox.py`](https://github.com/topoteretes/cognee/blob/dev/examples/guides/dropbox.py).

## Limitations

* **Only some file types are indexed** — text, Markdown, CSV, PDF and Paper docs. Office files, images and web links are skipped.
* **Team spaces are not supported.** In a Dropbox team space a member sees only their member folder; team folders outside it are not listed. The sync reports it once in `team_space_unsupported`.
* **No "select all".** Folders must be picked explicitly, and no selected folder may sit inside another.
* **`forget()` leaves the staging copy.** `forget(data_id=...)` and `forget(dataset=...)` remove a file from the graph and vectors but not from the connector's staging table and cursor, so an unchanged Dropbox brings nothing new on the next sync. Deselecting a folder empties its staging table.
* **A restored file may get a new Dropbox file id**, which makes it a new document.
* **No webhooks.** Memory is updated only by `/sync`, a changed selection, or a sync policy with the scheduler enabled.

## Troubleshooting

> [accordion] The server does not start after setting `DROPBOX_MAX_FILE_SIZE_MB`
>
> The value must be a positive number. `0`, negative numbers, `inf`, `nan` and text stop the server at startup. Leave it blank or unset for the default of 50.

> [accordion] `PUT /resources` returns 422 `A selected Dropbox folder could not be found; pick it again from the list`
>
> One of the ids no longer resolves at Dropbox — the folder was deleted or the account cannot see it. List the folders again with `GET /resources` and save ids from that list.

> [accordion] `PUT /resources` returns 422 `A selected Dropbox folder is inside another selected folder`
>
> Select either the parent or the subfolder, not both. Each selected folder is read recursively, so the parent already covers the subfolder.

> [accordion] `PUT /resources` returns 502 `Could not check the dropbox selection; try again`
>
> Dropbox could not be reached, answered with an error, or refused the token. The backend log has the cause. If it persists, reconnect the account.

> [accordion] `syncStatus: "degraded"` with `failed_account`
>
> The stored token belongs to a different Dropbox account than the connection. This is not an expired token, so reconnecting the same account does not fix it; disconnect and connect the right account.

> [accordion] `syncStatus: "degraded"` with `failed_retry`
>
> Some files could not be downloaded. They are retried on every sync, and their stored text is kept until Dropbox reports them changed or gone, so the connection stays degraded until they succeed.

> [accordion] `syncStatus: "degraded"` with `failed_auth`
>
> Dropbox refused the token or the app was removed from the account. Reconnect. A token missing a scope also lands here; check the app's permissions and reconnect.

> [accordion] Team folders are missing
>
> Team spaces are not supported; `team_space_unsupported` is `1` in `syncCounts`. Only the member's own folder is listed.

> [accordion] A file is missing
>
> Check `syncCounts`: `skipped_unsupported_type` (not a text, Markdown, CSV, PDF or Paper file), `skipped_too_large` (over `DROPBOX_MAX_FILE_SIZE_MB`), or `skipped_unparseable` (a PDF `pypdf` cannot read, or a binary file).

## Related

> [card] [Google Drive](https://docs.cognee.ai/integrations/google-drive-integration.md)
>
> The folder-based Google connector, with the same connect flow, connection state and sync policies.

> [card] [Notion](https://docs.cognee.ai/integrations/notion-integration.md)
>
> Connect a Notion workspace over OAuth and sync the pages you pick.


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