A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Dropbox API is how an app or AI agent works with a Dropbox account: listing a folder, uploading or downloading a file, moving and deleting content, searching, sharing files through links, and reading the account's profile and storage. Access is granted through an OAuth 2.0 access token, and the scopes on that token, like files.content.read or sharing.write, decide which actions it can take. Dropbox notifies an app of file changes through webhooks, so an integration learns about new or edited files without polling.
How an app or AI agent connects to Dropbox determines what it can reach. There is the HTTP API for making calls, a webhook channel for being told when files change, and a hosted server that exposes Dropbox tools to agents, and each is governed by the access token behind it and the scopes that token carries.
The Dropbox HTTP API is version 2, served from api.dropboxapi.com for calls and content.dropboxapi.com for file bytes. Every endpoint is a POST. Calls come in three styles: RPC, with JSON request and response bodies; upload, with the file bytes in the body and JSON arguments in the Dropbox-API-Arg header; and download, with JSON arguments in the header and the file bytes in the response. A call authenticates with a Bearer access token, and the scopes on that token decide what it can reach.
Dropbox sends an HTTP POST to a webhook URL registered in the App Console when files change in a connected account. The URL is first verified with a GET request carrying a challenge parameter that the app echoes back. A notification names which accounts changed, not what changed, so the app calls list_folder/continue with a stored cursor to read the actual changes. The app must respond within 10 seconds, and the files.metadata.read scope is required.
A hosted Model Context Protocol server at https://mcp.dropbox.com/mcp exposes Dropbox tools to AI agents and MCP clients, in beta. It authenticates with Dropbox OAuth and exposes 23 tools covering file operations like ListFolder, GetFileContent, CreateFile, and Delete, metadata like GetFileMetadata and GetUsageAndQuota, sharing like CreateSharedLink and ListSharedLinks, plus search, versioning and restore, and job-status tracking. Supported clients include Claude Code, Claude Web, ChatGPT Codex, ChatGPT Web, and Cursor.
Dropbox uses the OAuth 2.0 authorization-code flow. A user is redirected to Dropbox to authorize the app, and the returned code is exchanged at /oauth2/token for a short-lived access token that expires after a few hours. The token is sent as a Bearer token, and the scopes granted at authorization decide what it can reach. Long-lived tokens are deprecated.
Requesting offline access with token_access_type=offline returns a long-lived refresh token alongside the short-lived access token. The app exchanges the refresh token at /oauth2/token for a new access token when the old one expires, so it can keep acting without the user present. The flow uses PKCE for desktop, mobile, and single-page apps.
An app is created as either app-folder, scoped to a single dedicated folder Dropbox creates for it, or full-Dropbox, able to reach the whole account. On top of that, the app selects individual scopes, like files.content.read or sharing.write, that the access token then carries. The access type sets the boundary of what is reachable; the scopes set which actions are allowed within it.
The Dropbox API is split into areas an agent can act on, like files and folders, sharing, file requests, users, and account. Each area has its own methods and its own scopes, and writes in the files area move and delete real content.
List, read, upload, move, copy, delete, and search files and folders, and restore earlier versions.
Create and revoke shared links, share folders, and add or list the members of a shared file or folder.
Create and manage file requests, the links that let people upload files into a chosen folder.
Read the signed-in account, look up other accounts, and read how much storage space is used.
Update account-level settings, like the profile photo.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Files & foldersList, read, upload, move, copy, delete, and search files and folders, and restore earlier versions.16 | ||||||
| POST | /2/files/list_folder | List the contents of a folder, returning file and folder metadata with a cursor for paging and change-tracking. | read | files.metadata.read | Current | |
Returns a cursor used by list_folder/continue and by webhook handlers. Acts onfolder Permission (capability) files.metadata.readVersionAvailable since the API’s base version Webhook event file_changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/list_folder/continue | Fetch the next page of a folder listing, or the changes since a stored cursor. | read | files.metadata.read | Current | |
The endpoint a webhook handler calls to read what actually changed. Acts onfolder Permission (capability) files.metadata.readVersionAvailable since the API’s base version Webhook event file_changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/get_metadata | Get the metadata for a single file or folder, like its name, path, size, and revision. | read | files.metadata.read | Current | |
Read-only; returns metadata, not file contents. Acts onfile Permission (capability) files.metadata.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/search_v2 | Search for files and folders by name and other criteria across the account. | read | files.metadata.read | Current | |
Paginate further results with search/continue_v2. Acts onsearch Permission (capability) files.metadata.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/download | Download a file's contents. The JSON arguments go in the Dropbox-API-Arg header and the bytes come back in the response body. | read | files.content.read | Current | |
A content read; reaches the actual file bytes, not just metadata. Acts onfile Permission (capability) files.content.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/get_temporary_link | Get a short-lived direct link to download a file's contents without an access token. | read | files.content.read | Current | |
The link is unauthenticated and expires; anyone with it can download until it does. Acts onfile Permission (capability) files.content.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/upload | Upload a file's contents in a single request. The bytes go in the body and the JSON arguments in the Dropbox-API-Arg header. | write | files.content.write | Current | |
A single request should not exceed 150 MB; use an upload session for larger files. Acts onfile Permission (capability) files.content.writeVersionAvailable since the API’s base version Webhook event file_changeRate limitOver-frequent writes to one namespace return 429 too_many_write_operations. SourceOfficial documentation ↗ | ||||||
| POST | /2/files/upload_session/start | Begin an upload session to send a large file in chunks. | write | files.content.write | Current | |
An upload session supports files up to 350 GB across many append calls. Acts onfile Permission (capability) files.content.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/upload_session/finish | Complete an upload session, committing the uploaded chunks to a path. | write | files.content.write | Current | |
Writes the assembled file to the account. Acts onfile Permission (capability) files.content.writeVersionAvailable since the API’s base version Webhook event file_changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/move_v2 | Move or rename a file or folder to a new path. | write | files.content.write | Current | |
Changes where content lives; the original path no longer holds it. Acts onfile Permission (capability) files.content.writeVersionAvailable since the API’s base version Webhook event file_changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/copy_v2 | Copy a file or folder to a new path. | write | files.content.write | Current | |
Creates a new copy; the original is left in place. Acts onfile Permission (capability) files.content.writeVersionAvailable since the API’s base version Webhook event file_changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/create_folder_v2 | Create a folder at a given path. | write | files.content.write | Current | |
A core write. Acts onfolder Permission (capability) files.content.writeVersionAvailable since the API’s base version Webhook event file_changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/delete_v2 | Delete a file or folder, sending it to the account's deleted items where it can later be restored. | write | files.content.write | Current | |
Recoverable from deleted items; permanently_delete removes it for good. Acts onfile Permission (capability) files.content.writeVersionAvailable since the API’s base version Webhook event file_changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/permanently_delete | Permanently delete a file or folder so it cannot be restored. | write | files.permanent_delete | Current | |
Irreversible, and needs the separate files.permanent_delete scope rather than files.content.write. Acts onfile Permission (capability) files.permanent_deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/restore | Restore a file to a specific earlier revision. | write | files.content.write | Current | |
Overwrites the current contents with the chosen revision. Acts onfile Permission (capability) files.content.writeVersionAvailable since the API’s base version Webhook event file_changeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/files/list_revisions | List the saved revisions of a file. | read | files.metadata.read | Current | |
Read-only; returns revision metadata used by restore. Acts onfile Permission (capability) files.metadata.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SharingCreate and revoke shared links, share folders, and add or list the members of a shared file or folder.5 | ||||||
| POST | /2/sharing/list_shared_links | List the shared links for files and folders in the account. | read | sharing.read | Current | |
Read-only; returns existing links and their settings. Acts onshared_link Permission (capability) sharing.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/sharing/create_shared_link_with_settings | Create a shared link to a file or folder, with optional settings like password and expiry. | write | sharing.write | Current | |
Anyone with the resulting link can reach the content within its settings. Acts onshared_link Permission (capability) sharing.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/sharing/revoke_shared_link | Revoke a shared link so it can no longer be used to reach the content. | write | sharing.write | Current | |
The link stops working immediately. Acts onshared_link Permission (capability) sharing.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/sharing/add_folder_member | Add one or more members to a shared folder, by email or Dropbox account. | write | sharing.write | Current | |
Grants the named people access to the folder's contents. Acts onshared_folder Permission (capability) sharing.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/sharing/list_folder_members | List the members of a shared folder and their access levels. | read | sharing.read | Current | |
Read-only; returns who can reach the folder. Acts onshared_folder Permission (capability) sharing.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
File requestsCreate and manage file requests, the links that let people upload files into a chosen folder.2 | ||||||
| POST | /2/file_requests/create | Create a file request, a link that lets people upload files into a chosen folder. | write | file_requests.write | Current | |
Opens a route for outsiders to upload into the account's chosen folder. Acts onfile_request Permission (capability) file_requests.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/file_requests/list_v2 | List the file requests on the account. | read | file_requests.read | Current | |
Read-only; paginate further results with list/continue. Acts onfile_request Permission (capability) file_requests.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead the signed-in account, look up other accounts, and read how much storage space is used.3 | ||||||
| POST | /2/users/get_current_account | Get the profile of the account linked to the access token, like name, email, and account id. | read | account_info.read | Current | |
Read-only; returns the signed-in user's profile. Acts onaccount Permission (capability) account_info.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/users/get_space_usage | Get the storage space currently used by the account and its allocation. | read | account_info.read | Current | |
Read-only; returns used and allocated bytes. Acts onaccount Permission (capability) account_info.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /2/users/get_account | Look up another Dropbox account by its account id. | read | sharing.read | Current | |
Read-only; uses the sharing.read scope to read a basic public profile of another account. Acts onaccount Permission (capability) sharing.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountUpdate account-level settings, like the profile photo.1 | ||||||
| POST | /2/account/set_profile_photo | Set the profile photo for the signed-in account. | write | account_info.write | Current | |
Changes account-level profile settings. Acts onaccount Permission (capability) account_info.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Dropbox can notify an app when files change in a connected account, instead of the app repeatedly asking. A notification says which accounts changed, not what changed, so the app then calls list_folder/continue with a stored cursor to read the actual changes.
| Event | What it signals | Triggered by |
|---|---|---|
list_folder (account changed) | Files were added, removed, or changed in a connected account. The notification names the account ids that changed, not the specific files, so the app calls list_folder/continue with a stored cursor to read what changed. | /2/files/upload/2/files/upload_session/finish/2/files/move_v2/2/files/copy_v2/2/files/create_folder_v2/2/files/delete_v2/2/files/restore |
Dropbox limits how fast and how much an app can call, by a per-authorization request rate and by separate caps on upload size, with a single upload request held to 150 MB.
Dropbox enforces rate limits per authorization, that is per linked user for a user app, or per team for a team app calling Business Endpoints. The exact numbers are not published and are set so as not to inhibit normal apps. Going over returns HTTP 429: too_many_requests for the general rate limit, or too_many_write_operations when too many writes land on one namespace at once. A 429 response carries a Retry-After header giving the seconds to wait before retrying; if it is absent, the app should back off exponentially. Rate-limited requests still count toward the limit, so tight retry loops make it worse.
List endpoints return a cursor and a has_more flag. The app pages by calling the matching continue endpoint with the cursor, like list_folder/continue after list_folder, or search/continue_v2 after search_v2. A stored list_folder cursor also serves as a change-tracking marker, returning only what changed since it was issued, which is how webhook handlers read updates.
A single /2/files/upload request should not exceed 150 MB; larger files use an upload session, which supports files up to 350 GB across many append calls, ideally in multiples of 4 MB. An upload-session batch can commit up to 1,000 files to a namespace at once to reduce write contention.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | Something is wrong with the request itself, like malformed JSON, a failed validation, or calling an endpoint the app's access type can't use. | Read the plaintext error message, fix the request, and resend. It won't succeed on retry as-is. |
| 401 | invalid_access_token / expired_access_token | The Bearer token is invalid, expired, lacks the required scope, or the user revoked access or was suspended. | Refresh the access token, or prompt the user to re-authenticate, and confirm the token carries the scope the call needs. |
| 403 | access_denied | The user or team lacks access to the operation, often from a plan downgrade or an account limit like a monthly upload cap. | It may succeed later, but only after the account is changed. Back off for background work. |
| 409 | endpoint-specific error | An endpoint-specific error described by the error JSON, like path/not_found when content was moved or deleted. The error object carries a .tag naming the case. | Branch on the error .tag for that endpoint and handle the named case; the endpoint docs list the possibilities. |
| 429 | too_many_requests / too_many_write_operations | A rate limit was hit. too_many_requests is the general per-authorization rate limit; too_many_write_operations means too many writes are landing on the same namespace at once. | Wait the number of seconds in the Retry-After header before retrying; if there is none, back off exponentially. For write contention, reduce parallel writes to the namespace. |
| 500 | internal_error | An error on Dropbox's side, expected to be temporary. | Retry with exponential backoff; check status.dropbox.com or contact support if it persists. |
Dropbox runs one stable version of its HTTP API, version 2, with no dated version to pin. New methods ship as suffixed versions of a route, like move_v2 alongside the original move, so older calls keep working.
Version 2 is the current Dropbox HTTP API, served under /2, replacing the retired v1. It has no dated version to pin; behavioural changes to a method ship as a new suffixed route, like move_v2 or search_v2, so older calls keep working until an app moves to the newer form.
The original Dropbox API v1 was deprecated and shut down, with v2 as its replacement. New integrations use v2 only.
Move to the _v2 form of a method when adopting its newer behaviour.
Dropbox API changelog ↗Bollard AI sits between a team's AI agents and Dropbox. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.