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
httpxclient andpypdf, both core dependencies.
Prerequisites
- Cognee
v1.6.9or 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:8000works 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
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: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:
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:
Syncing and Status
Connecting does not start a sync. Start one by saving a changed selection, by calling/sync, or with a sync policy:
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_gonewhile 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.
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 withinvalid_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
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_idis a folder id (id:..., theidthat Dropbox’s/2/files/get_metadatareturns for a path) or"". A path such as/Notesis refused.resource_namenames the staging table and the cursor. It must start withdropbox_and hold only lowercase letters, digits and single underscores (at most 63 characters), ordropbox_source()raisesValueError. 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.tokenis a string or a callable that returns a fresh token. In a script there is no file size limit unless you passmax_file_size_mb.- A normal return is not proof of a finished sync: check
source.cognee_sync_stats(failed == 0andcomplete == 1).
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=...)andforget(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 server does not start after setting DROPBOX_MAX_FILE_SIZE_MB
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.PUT /resources returns 422 A selected Dropbox folder could not be found; pick it again from the list
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.PUT /resources returns 422 A selected Dropbox folder is inside another selected folder
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.
PUT /resources returns 502 Could not check the dropbox selection; try again
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.
syncStatus: "degraded" with failed_account
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.
syncStatus: "degraded" with failed_retry
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.
syncStatus: "degraded" with failed_auth
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.
Team folders are missing
Team folders are missing
Team spaces are not supported;
team_space_unsupported is 1 in syncCounts. Only the member’s own folder is listed.A file is missing
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
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.