Dropbox
Use this skill when the user asks about their Dropbox files or folders — listing,
searching, reading/downloading, uploading, or sharing.
This is an OAuth connector. The resolved user's Dropbox token already lives on your
computer as an environment variable, one per Dropbox API host (the way a logged-in CLI's
cached credential would):
$VAULT_TOKEN_API_DROPBOXAPI_COM — for api.dropboxapi.com (RPC: list, search, share, move, delete)$VAULT_TOKEN_CONTENT_DROPBOXAPI_COM — for content.dropboxapi.com (download, upload)
Both carry the same Dropbox token (one OAuth grant spans every host), so if a
host-specific var is empty, $VAULT_TOKEN_API_DROPBOXAPI_COM works as the bearer for any
Dropbox host. Pass it as -H "Authorization: Bearer $VAULT_TOKEN_...". Never ask the user
for a token, log it, or use another principal's credential or a service fallback.
If $VAULT_TOKEN_API_DROPBOXAPI_COM is empty: per-user connector tokens are injected
only in a direct DM with the user (their personal scope) — in a channel or group
they're absent by design, even for a fully-connected user. So don't tell a channel user to
reconnect; ask them to DM you to run this. Only if it's empty inside a DM does it mean they
haven't connected Dropbox — then point them to the Connectors page.
On 401: the token is expired/invalid → have them reconnect — unless the error body's
.tag is missing_scope, in which case the app lacks a permission; name the required_scope
it returns (the connected app grants account_info.read, files.metadata.read,
files.content.read/write, sharing.read/write).
First: pick the right namespace (team vs personal)
This is the step that makes team and shared folders visible. By default the Dropbox
API only lists the user's personal (home) namespace — for a Business member that root
is often nearly empty. The team folders they see in the Dropbox web UI live in the
team namespace, and the API only shows them when you set the Dropbox-API-Path-Root
header.
Resolve the account's namespaces once, then reuse the root_namespace_id for the rest of
the session — it doesn't change. This endpoint takes no arguments: send no request body
and no Content-Type (adding Content-Type: application/json with an empty body returns
a 400):
curl -sS -X POST 'https://api.dropboxapi.com/2/users/get_current_account' \
-H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM"
Read root_info from the response. If root_info[".tag"] is team, use its
root_namespace_id to see everything (team folders + the member's own files); if it is
user (individual account), the default root is fine and no header is needed.
When you have a root_namespace_id, add this header to every files/sharing call so
your view matches the web UI (substitute the id):
-H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}'
Prefer referencing items by id ("id:...", returned by list/search) over path
strings — ids are stable across namespaces and avoid path-escaping issues.
List a folder
path is "" for the root of the active namespace, or a folder path/id:
curl -sS -X POST 'https://api.dropboxapi.com/2/files/list_folder' \
-H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
-H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
-H 'Content-Type: application/json' \
--data '{"path":"","recursive":false}'
For an ls -R-style or find-across-a-tree request, set "recursive":true to stream the
whole subtree in one paginated pass instead of walking folder by folder.
If the response has "has_more":true, page with the returned cursor:
curl -sS -X POST 'https://api.dropboxapi.com/2/files/list_folder/continue' \
-H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
-H 'Content-Type: application/json' \
--data '{"cursor":"CURSOR"}'
Search
curl -sS -X POST 'https://api.dropboxapi.com/2/files/search_v2' \
-H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
-H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
-H 'Content-Type: application/json' \
--data '{"query":"budget","options":{"max_results":100}}'
If the response has "has_more": true, keep fetching with its cursor via
files/search/continue_v2 (same shape as list_folder/continue above) before
concluding a file doesn't exist.
Read / download a file
Downloads use the content host and carry their argument in the Dropbox-API-Arg header
(no JSON body). Reference the file by id or path:
curl -sS -X POST 'https://content.dropboxapi.com/2/files/download' \
-H "Authorization: Bearer $VAULT_TOKEN_CONTENT_DROPBOXAPI_COM" \
-H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
-H 'Dropbox-API-Arg: {"path":"id:FILE_ID"}' \
-o inbox/dropbox-file.bin
Keep source paths/ids in your answer so claims can be traced.
Writes require approval
Uploading, sharing, moving, and deleting are writes. Prepare the exact change, name the
target file/folder (id + path), and get approval before running it.
Upload bytes you produced (content host; the arg is a header, the file is the body):
curl -sS -X POST 'https://content.dropboxapi.com/2/files/upload' \
-H "Authorization: Bearer $VAULT_TOKEN_CONTENT_DROPBOXAPI_COM" \
-H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
-H 'Dropbox-API-Arg: {"path":"/Reports/q3.pdf","mode":"add","autorename":true}' \
-H 'Content-Type: application/octet-stream' \
--data-binary @q3.pdf
Create a shared link (returns a url; a 409 shared_link_already_exists carries the
existing link in its metadata — reuse it):
curl -sS -X POST 'https://api.dropboxapi.com/2/sharing/create_shared_link_with_settings' \
-H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
-H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
-H 'Content-Type: application/json' \
--data '{"path":"id:FILE_ID"}'
Move/rename or delete (delete_v2 is recoverable — the file goes to the user's deleted
files, not a permanent purge):
curl -sS -X POST 'https://api.dropboxapi.com/2/files/move_v2' \
-H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
-H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
-H 'Content-Type: application/json' \
--data '{"from_path":"id:FILE_ID","to_path":"/Archive/q3.pdf"}'
curl -sS -X POST 'https://api.dropboxapi.com/2/files/delete_v2' \
-H "Authorization: Bearer $VAULT_TOKEN_API_DROPBOXAPI_COM" \
-H 'Dropbox-API-Path-Root: {".tag":"root","root":"ROOT_NAMESPACE_ID"}' \
-H 'Content-Type: application/json' \
--data '{"path":"id:FILE_ID"}'
Always report the file path/id and what changed, plus any shared link you created.