dropbox
Browse, search, read, upload, and share the user's Dropbox — including team/shared folders — through their own Dropbox connection.
- License 许可
- MIT
- 所属仓库
- yc-software/qm
- 最近更新
- 2026-11-15
- Stars
- ★ 1.6w
- Forks
- 2.0k
01 前言 Front Matter
- name
- dropbox
- description
- Browse, search, read, upload, and share the user's Dropbox — including team/shared folders — through their own Dropbox connection.
- requiredCapabilities
- [ "egress:api.dropboxapi.com", "egress:content.dropboxapi.com" ]
03 SKILL.md 正文
Dropbox
Use this skill when the user asks about their Dropbox files or folders — listing, searching, reading/downloading, uploading, or sharing.
Connection
Dropbox reaches you one of two ways; the requests are the same either way.
-
Direct token:
$VAULT_TOKEN_API_DROPBOXAPI_COM(api.dropboxapi.com: list, search, share, move, delete) and$VAULT_TOKEN_CONTENT_DROPBOXAPI_COM(content.dropboxapi.com: download, upload) carry the same token, so if a host-specific one is empty,$VAULT_TOKEN_API_DROPBOXAPI_COMworks for any Dropbox host. Pass it as-H "Authorization: Bearer $VAULT_TOKEN_..."on every call; nothing on the network path adds it for you. Thecurlexamples below use it as written. -
App connection: with no token, the user connects Dropbox as an app instead (composio skill). Send the same request through QM — same method, URL,
query, headers and JSONbody, but no Authorization header:curl -sS "$AGENT_API_URL/v1/composio/proxy" -H "X-Agent-Capability: $AGENT_API_TOKEN" \ -H 'content-type: application/json' \ --data '{"method":"POST","url":"https://api.dropboxapi.com/2/users/get_current_account"}'The reply is the provider's own status and body; the composio skill's "Raw requests" section covers
409answers, choosing an account, and file bodies. PassDropbox-API-Arginheaders.
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 and there is no app connection either: 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 400 Invalid authorization value: the header was missing or empty, so Dropbox
never checked the token. Fix your command (echo ${#VAULT_TOKEN_API_DROPBOXAPI_COM} shows
the variable is set) and retry; this says nothing about the user's connection. Before
telling a user Dropbox is broken, confirm with users/get_current_account below.
On 401 (invalid_access_token, expired_access_token): the token was sent and
rejected → 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.
04 同仓库更多 Skills
zoom
Find, create, reschedule, and cancel the user's Zoom meetings through their own Zoom connection.
use-shared-credential
When you need to call a service the org has a SHARED credential for (a SERP/search key, a paid-API key, a data-vendor feed, a Git remote) — and the platform has told you that credential is available to this conversation — make the call BY PROXY through the credential broker. You never see the secret; the core stamps it onto the outbound request for you.
ui-state
See what the person is looking at in the QM web UI right now — the whole page (sidebar, every multiview pane, open dialogs) as raw HTML, the app's state as JSON, optionally the CSS and a screenshot. Use when they ask about something on their screen, want help with the UI, or you need to check what a canvas you wrote actually rendered.
ui-canvas
Draw your own HTML/CSS/JS as a full-window overlay on top of the QM web UI — a dashboard, a form, a visualization, controls that message you back. Write, update, replace, pin or dismiss it. Use when an interactive or visual result beats a chat reply.
taste-skill
Design taste and process for anything a person will look at in a browser — landing page, dashboard, prototype, deck. The default design driver for a browsable artifact, with an anti-slop playbook for the visual language.
slack-drafts
Create Slack message drafts in the user's own composer, as the user, through their per-user Slack OAuth. Drafting only — the user reviews and sends from Slack.