Skip to main content
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.
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.

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.
  • 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.
  • 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, create an app, then: 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): 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

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>:

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:
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:
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:
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:
The sync runs detached and fans out over the selected folders, one source per folder, each ingested through 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, with the dropbox prefix and a hash of the Dropbox account id.

What gets indexed

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); 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:

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

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:
  • 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.

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

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.
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.
Select either the parent or the subfolder, not both. Each selected folder is read recursively, so the parent already covers the subfolder.
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.
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.
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.
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.
Team spaces are not supported; team_space_unsupported is 1 in syncCounts. Only the member’s own folder is listed.
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).

Google Drive

The folder-based Google connector, with the same connect flow, connection state and sync policies.

Notion

Connect a Notion workspace over OAuth and sync the pages you pick.