<!-- Generated by `just docs` from catalog/toolkits/dropbox.yaml, catalog/expansions/dropbox.yaml, catalog/evals/scorecard.json. Edit the source, not this file. -->

# Dropbox

Cloud files. List, search, upload, and organize files and folders, share them with links, and handle file requests.

| Property | Value |
| --- | --- |
| Slug | `dropbox` |
| Definition version | `0.1.0` |
| Base URL | `https://api.dropboxapi.com` |
| Auth schemes | `oauth2` |
| Action tools | 31 |
| By class | 13 read, 11 write, 7 destructive |
| Triggers | 1 |
| Provider rate limit | not declared, so outbound calls are unpaced |

## Measured routing accuracy

49 golden cases replayed through the router over the whole index: measured over corpus `ea4f12ad2948` (65 toolkits, 2283 tools indexed and 13 declared uncallable), 31 cases written by hand and 18 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

| Measure | Cases | Share |
| --- | --- | --- |
| top-1 | 17/49 | 34.7% |
| top-8 | 42/49 | 85.7% |

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. `just eval-live` measures the same cases through the live reranker.

## Authentication

Connect an entity with `ConnectionsService.InitiateConnection`, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

### `oauth2`

| Property | Value |
| --- | --- |
| Authorization URL | `https://www.dropbox.com/oauth2/authorize` |
| Token URL | `https://api.dropboxapi.com/oauth2/token` |
| Default scopes | `files.metadata.read`, `files.content.read`, `files.content.write`, `sharing.read`, `sharing.write`, `account_info.read`, `file_requests.read`, `file_requests.write` |
| Refresh tokens | yes, the refresh daemon renews ahead of expiry |

## Tools

31 action tools. The catalog-wide slug is `dropbox.<tool>`, which is what `search_tools` returns and `call_tool` takes.

### `dropbox.list_folder`

List the files and folders directly inside a Dropbox folder. Use for what's in this folder or browsing a known location. For finding a file by name or content anywhere in the account, use search_files.

Class `read` (reads only). Scopes `files.metadata.read`. Calls `POST /2/files/list_folder`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | no | Folder path, e.g. "/Projects/Q3". Pass an empty string "" to list the root of the account. |
| `recursive` | boolean | no | Include subfolder contents too. Defaults to false. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `cursor` | string |  |
| `entries` | array of object |  |
| `entries[]..tag` | string |  |
| `entries[].id` | string |  |
| `entries[].name` | string |  |
| `entries[].path_display` | string |  |
| `entries[].server_modified` | string (date-time) |  |
| `entries[].size` | integer |  |
| `has_more` | boolean |  |

Also retrieved by: "what's in this folder", "browse this directory", "show me what's inside here", "what's stored in this location".

### `dropbox.search_files`

Search the whole Dropbox account by name or content. Use when the user wants to find, look up, or locate something by keyword rather than browse a folder they already know. Optionally scope the search to one folder.

Class `read` (reads only). Scopes `files.metadata.read`. Calls `POST /2/files/search_v2`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `max_results` | integer | no | Results to return, max 1000. Defaults to 100. |
| `path` | string | no | Restrict the search to this folder path. Omit to search everywhere. |
| `query` | string | **yes** | Search text, e.g. "budget proposal" or "quarterly report". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `has_more` | boolean |  |
| `matches` | array of object |  |
| `matches[].metadata` | object |  |
| `matches[].metadata..tag` | string |  |
| `matches[].metadata.id` | string |  |
| `matches[].metadata.name` | string |  |
| `matches[].metadata.path_display` | string |  |
| `matches[].metadata.size` | integer |  |

Also retrieved by: "find something by keyword", "look up an old document", "dig up anything mentioning the budget", "where did I save that".

### `dropbox.get_metadata`

Get one file or folder's metadata by path: name, size, type, and when it last changed. Use when the user names a specific file or folder. For its actual content, use download_file.

Class `read` (reads only). Scopes `files.metadata.read`. Calls `POST /2/files/get_metadata`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | **yes** | Dropbox path, e.g. "/Projects/Q3/budget.xlsx". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `.tag` | string |  |
| `client_modified` | string (date-time) |  |
| `id` | string |  |
| `name` | string |  |
| `path_display` | string |  |
| `rev` | string |  |
| `server_modified` | string (date-time) |  |
| `size` | integer |  |

Also retrieved by: "how big is this", "when was this last touched", "check the details on this item", "who last changed this".

### `dropbox.download_file`

Download the raw content of a file by path. Use when the user wants to fetch, save, or read what's inside a file. For a quick visual preview of an image instead of the full file, use get_thumbnail.

Class `read` (reads only). Scopes `files.content.read`. Calls `POST /2/files/download`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | **yes** | Dropbox path of the file to download. |

Also retrieved by: "grab a copy of this", "save this to my computer", "fetch the actual bytes", "pull this down locally".

### `dropbox.get_temporary_link`

Get a direct download link for a file that works without Dropbox sign-in, valid for a few hours. Use when the user wants a quick link to hand someone rather than a lasting shared link (use create_shared_link for that).

Class `read` (reads only). Scopes `files.content.read`. Calls `POST /2/files/get_temporary_link`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | **yes** | Dropbox path of the file to link to. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `link` | string |  |
| `metadata` | object |  |
| `metadata.name` | string |  |
| `metadata.path_display` | string |  |

Also retrieved by: "give me a quick link that doesn't need sign-in", "I need a link that expires soon", "send a link that works without an account", "a link good for just a few hours".

### `dropbox.get_thumbnail`

Get a small preview image for a photo or image file. Use when the user wants to see what a picture looks like without downloading the full file.

Class `read` (reads only). Scopes `files.content.read`. Calls `POST /2/files/get_thumbnail_v2`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `format` | string, one of jpeg, png | no | Thumbnail image format. Defaults to jpeg. |
| `path` | string | **yes** | Dropbox path of the image file. |
| `size` | string, one of w32h32, w64h64, w128h128, w256h256, w480h320, w640h480, w960h640, w1024h768 | no | Thumbnail dimensions. Defaults to w64h64. |

Also retrieved by: "show me a small preview of this picture", "what does this image look like", "give me a quick look at this photo", "preview this picture without opening it".

### `dropbox.upload_file`

Create a new file in Dropbox with the given content. Use when the user wants to add, save, or upload a document or note. Content is UTF-8 text, base64-encoded. Fails if a file already exists at that path; to overwrite one, use update_file_content.

Class `write` (writes, no confirmation needed). Scopes `files.content.write`. Calls `POST /2/files/upload`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `content` | string | **yes** | File content, base64-encoded. |
| `path` | string | **yes** | Destination path, e.g. "/Notes/meeting.txt". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `path_display` | string |  |
| `rev` | string |  |

Also retrieved by: "save this write-up online", "stash this note in my account", "put this text into a new document", "add a fresh item with this content".

### `dropbox.update_file_content`

Replace an existing file's content with new text, keeping its path. Use when the user wants to overwrite, update, or rewrite what's inside a file. Content is UTF-8 text, base64-encoded.

Class `write` (writes, no confirmation needed). Scopes `files.content.write`. Calls `POST /2/files/upload`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `content` | string | **yes** | New file content, base64-encoded. |
| `path` | string | **yes** | Path of the existing file to overwrite. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string |  |
| `rev` | string |  |
| `server_modified` | string (date-time) |  |

Also retrieved by: "overwrite what's inside this", "replace the text in that document", "rewrite this with new content", "swap out what's currently there".

### `dropbox.create_folder`

Create a new folder in Dropbox at the given path, including any missing parent folders. Use when the user wants to organize files into a new folder or directory.

Class `write` (writes, no confirmation needed). Scopes `files.content.write`. Calls `POST /2/files/create_folder_v2`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | **yes** | New folder path, e.g. "/Projects/Q3 Reports". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `path_display` | string |  |

Also retrieved by: "make a new directory for this", "set up a place to keep these organized", "I need somewhere to put all this".

### `dropbox.rename_file`

Rename a file or folder by giving it a new path, keeping its content and parent folder. Use when the user wants to retitle or relabel something already in Dropbox. For putting it in a different folder, use move_file.

Class `write` (writes, no confirmation needed). Scopes `files.content.write`. Calls `POST /2/files/move_v2`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `from_path` | string | **yes** | Current path of the file or folder. |
| `to_path` | string | **yes** | New full path with the new name, e.g. "/Reports/Final Budget.xlsx". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `metadata` | object |  |
| `metadata..tag` | string |  |
| `metadata.name` | string |  |
| `metadata.path_display` | string |  |

Also retrieved by: "retitle this", "give this a better name", "this is labeled wrong, fix the name", "change what this is called".

### `dropbox.move_file`

Move a file or folder into a different folder, keeping its name. Use when the user wants to relocate, file away, or reorganize something into another folder. For giving it a new name in place, use rename_file.

Class `write` (writes, no confirmation needed). Scopes `files.content.write`. Calls `POST /2/files/move_v2`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `from_path` | string | **yes** | Current path of the file or folder to move. |
| `to_path` | string | **yes** | Destination path, including the file or folder name. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `metadata` | object |  |
| `metadata..tag` | string |  |
| `metadata.name` | string |  |
| `metadata.path_display` | string |  |

Also retrieved by: "relocate this somewhere else", "put this in a different location", "this is in the wrong place".

### `dropbox.copy_file`

Duplicate a file or folder to another path, leaving the original in place. Use when the user wants their own copy or a template to build from.

Class `write` (writes, no confirmation needed). Scopes `files.content.write`. Calls `POST /2/files/copy_v2`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `from_path` | string | **yes** | Path of the file or folder to copy. |
| `to_path` | string | **yes** | Destination path for the copy. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `metadata` | object |  |
| `metadata..tag` | string |  |
| `metadata.name` | string |  |
| `metadata.path_display` | string |  |

Also retrieved by: "I want my own version of this", "duplicate this so I can edit it", "make a template from this".

### `dropbox.delete_file`

Delete a file or folder by path. Use when the user wants to remove or get rid of something in Dropbox. A deleted file's content stays recoverable for a time through restore_file; use list_revisions first to find which version to bring back.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `files.content.write`. Calls `POST /2/files/delete_v2`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | **yes** | Path of the file or folder to delete. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `metadata` | object |  |
| `metadata..tag` | string |  |
| `metadata.name` | string |  |
| `metadata.path_display` | string |  |

Also retrieved by: "get rid of this for good", "remove this, I don't need it anymore", "toss this old draft".

### `dropbox.restore_file`

Bring back a specific past revision of a file, whether it was deleted or just overwritten. Use when the user wants to undo a change or recover a version they lost. Requires the revision id from list_revisions.

Class `write` (writes, no confirmation needed). Scopes `files.content.write`. Calls `POST /2/files/restore`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | **yes** | Path the file lived (or lives) at. |
| `rev` | string | **yes** | Revision id to restore, from list_revisions. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string |  |
| `rev` | string |  |
| `server_modified` | string (date-time) |  |

Also retrieved by: "bring back an earlier version", "undo the last change to this", "I need the version from before".

### `dropbox.list_revisions`

List a file's past versions: each revision id, size, and when it was saved. Use when the user asks about earlier versions or wants to recover something they changed or deleted. Restore one with restore_file.

Class `read` (reads only). Scopes `files.metadata.read`. Calls `POST /2/files/list_revisions`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `limit` | integer | no | Number of revisions to return, max 100. Defaults to 10. |
| `path` | string | **yes** | Path of the file to list revisions for. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `entries` | array of object |  |
| `entries[].rev` | string |  |
| `entries[].server_modified` | string (date-time) |  |
| `entries[].size` | integer |  |
| `is_deleted` | boolean |  |

Also retrieved by: "show me the version history", "what did this look like before", "who edited this and when".

### `dropbox.create_shared_link`

Create a link to a file or folder that anyone with the URL can open. Use when the user wants to share, send, or get a link for something in Dropbox. Optionally protect it with a password or an expiry date.

Class `write` (writes, no confirmation needed). Scopes `sharing.write`. Calls `POST /2/sharing/create_shared_link_with_settings`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `expires` | string (date-time) | no | Optional time after which the link stops working. |
| `password` | string | no | Optional password required to open the link. |
| `path` | string | **yes** | Path of the file or folder to link to. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `.tag` | string |  |
| `path_lower` | string |  |
| `url` | string |  |

Also retrieved by: "give me a link anyone can open", "I want a URL for this I can send someone", "generate a public link to this".

### `dropbox.list_shared_links`

List the shareable links that exist for a file, or for the whole account when no path is given. Use when the user asks who has a link to something or wants to review what's been shared.

Class `read` (reads only). Scopes `sharing.read`. Calls `POST /2/sharing/list_shared_links`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | no | Restrict to links for this file or folder. Omit to list every link. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `links` | array of object |  |
| `links[]..tag` | string |  |
| `links[].name` | string |  |
| `links[].path_lower` | string |  |
| `links[].url` | string |  |

Also retrieved by: "who has a link to this", "what's been shared already", "check what links exist for this".

### `dropbox.revoke_shared_link`

Disable a shared link so it stops working. Use when the user wants to unshare, revoke, or kill a link they previously created, without touching the file itself.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `sharing.write`. Calls `POST /2/sharing/revoke_shared_link`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `url` | string | **yes** | The shared link URL to revoke. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `revoked` | boolean |  |

Also retrieved by: "kill that link I sent", "shut off access through that URL", "stop that link from working".

### `dropbox.share_folder`

Turn an existing folder into a shared folder so other people can be added to it. Use when the user wants to start collaborating on a folder with others. Add people to it afterward with add_folder_member.

Class `write` (writes, no confirmation needed). Scopes `sharing.write`. Calls `POST /2/sharing/share_folder`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `path` | string | **yes** | Path of the existing folder to share. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `.tag` | string |  |
| `shared_folder_id` | string |  |

Also retrieved by: "start collaborating on this with others", "let the team work on this together", "open this up for the group".

### `dropbox.list_shared_folders`

List the shared folders the signed-in account belongs to, owned by them or by someone else. Use when the user asks what team folders or shared folders they have access to.

Class `read` (reads only). Scopes `sharing.read`. Calls `POST /2/sharing/list_folders`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `page_size` | integer | no | Results per page, max 1000. Defaults to 100. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `cursor` | string |  |
| `entries` | array of object |  |
| `entries[].name` | string |  |
| `entries[].path_lower` | string |  |
| `entries[].shared_folder_id` | string |  |

Also retrieved by: "what team folders am I part of", "show the shared spaces I belong to", "which collaborative folders can I open".

### `dropbox.add_folder_member`

Invite a person by email to a shared folder, as a viewer or editor. Use when the user wants to add, invite, or give someone access to a shared folder. For a single file's link instead, use create_shared_link.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `sharing.write`. Calls `POST /2/sharing/add_folder_member`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `access_level` | string, one of viewer, editor | no | Access level to grant. Defaults to viewer. |
| `email` | string | **yes** | Email address of the person to invite. |
| `shared_folder_id` | string | **yes** | Id of the shared folder, from share_folder or list_shared_folders. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `invited` | boolean |  |

Also retrieved by: "invite someone to this shared space", "give a new person access to this", "let this person in on the shared work".

### `dropbox.list_folder_members`

List who has access to a shared folder and their role. Use when the user wants to see who can view or edit a shared folder, before changing its membership.

Class `read` (reads only). Scopes `sharing.read`. Calls `POST /2/sharing/list_folder_members`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `shared_folder_id` | string | **yes** | Id of the shared folder to check membership on. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `users` | array of object |  |
| `users[].access_type` | object |  |
| `users[].access_type..tag` | string |  |
| `users[].user` | object |  |
| `users[].user.account_id` | string |  |
| `users[].user.display_name` | string |  |
| `users[].user.email` | string |  |

Also retrieved by: "who's on this shared space", "see everyone with access here", "check the roster for this shared area".

### `dropbox.remove_folder_member`

Revoke a person's access to a shared folder. Use when the user wants to remove, kick out, or stop someone from seeing a shared folder.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `sharing.write`. Calls `POST /2/sharing/remove_folder_member`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `email` | string | **yes** | Email address of the person to remove. |
| `leave_a_copy` | boolean | no | Leave the removed person a private copy of the folder's current contents. Defaults to false. |
| `shared_folder_id` | string | **yes** | Id of the shared folder the person has access to. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `complete` | boolean |  |

Also retrieved by: "take this person off the shared space", "kick them out of this collaborative area", "cut their access to this".

### `dropbox.unshare_folder`

Turn a shared folder back into a private one, removing every other member's access at once. Use when the user wants to stop collaborating on a folder entirely, not just remove one person (use remove_folder_member for that).

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `sharing.write`. Calls `POST /2/sharing/unshare_folder`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `leave_a_copy` | boolean | no | Leave removed members a private copy of the folder's current contents. Defaults to false. |
| `shared_folder_id` | string | **yes** | Id of the shared folder to unshare. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `complete` | boolean |  |

Also retrieved by: "stop everyone's access to this at once", "take this back to being private", "end the collaboration on this entirely".

### `dropbox.accept_shared_folder`

Accept a shared folder someone invited the signed-in account to, so it shows up alongside their own folders. Use when the user wants to join, accept, or add a shared folder they were invited to.

Class `write` (writes, no confirmation needed). Scopes `sharing.write`. Calls `POST /2/sharing/mount_folder`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `shared_folder_id` | string | **yes** | Id of the shared folder to accept, from an invitation. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string |  |
| `path_lower` | string |  |
| `shared_folder_id` | string |  |

Also retrieved by: "join the thing someone invited me to", "add that invitation to my account", "I want to join what they shared with me".

### `dropbox.leave_shared_folder`

Give up the signed-in account's own access to a shared folder, leaving its other members unaffected. Use when the user wants to leave, exit, or step away from a folder someone else shared with them.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `sharing.write`. Calls `POST /2/sharing/relinquish_folder_membership`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `leave_a_copy` | boolean | no | Keep a private copy of the folder's current contents. Defaults to false. |
| `shared_folder_id` | string | **yes** | Id of the shared folder to leave. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `complete` | boolean |  |

Also retrieved by: "step away from this shared space", "I'm done being part of this", "take myself off this collaborative area".

### `dropbox.get_current_account`

Get the signed-in Dropbox account's name, email, and country. Use when the user asks who they're signed in as or wants their own account details.

Class `read` (reads only). Scopes `account_info.read`. Calls `POST /2/users/get_current_account`.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `account_id` | string |  |
| `country` | string |  |
| `email` | string |  |
| `name` | object |  |
| `name.display_name` | string |  |

Also retrieved by: "who am I signed in as", "show my own profile details", "what account is this".

### `dropbox.get_space_usage`

Get how much storage the signed-in account is using and its total allowance. Use when the user asks how much space they have left or how full their Dropbox is.

Class `read` (reads only). Scopes `account_info.read`. Calls `POST /2/users/get_space_usage`.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `allocation` | object |  |
| `allocation..tag` | string |  |
| `allocation.allocated` | integer |  |
| `used` | integer |  |

Also retrieved by: "how much room do I have left", "check my storage usage", "is my account almost full".

### `dropbox.create_file_request`

Create a file request: a page other people can use to upload files into a folder, without needing a Dropbox account of their own. Use when the user wants to collect, gather, or request files from someone external.

Class `write` (writes, no confirmation needed). Scopes `file_requests.write`. Calls `POST /2/file_requests/create`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `deadline` | string (date-time) | no | Optional deadline after which uploads are refused. |
| `destination` | string | **yes** | Folder path where uploaded files land. |
| `title` | string | **yes** | Title shown on the upload page, e.g. "Tax documents". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `destination` | string |  |
| `id` | string |  |
| `title` | string |  |
| `url` | string |  |

Also retrieved by: "set up a page for people to send me their stuff", "I need to collect documents from someone outside", "start gathering uploads from a client".

### `dropbox.list_file_requests`

List the file requests the signed-in account has created, open or closed. Use when the user asks what upload requests they've sent out or wants to check on one.

Class `read` (reads only). Scopes `file_requests.read`. Calls `POST /2/file_requests/list_v2`.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `file_requests` | array of object |  |
| `file_requests[].destination` | string |  |
| `file_requests[].id` | string |  |
| `file_requests[].is_open` | boolean |  |
| `file_requests[].title` | string |  |

Also retrieved by: "what upload pages have I set up", "show the collection requests I've sent out", "check on the things I asked people to send".

### `dropbox.delete_file_request`

Permanently delete one or more file requests, closing them to new uploads. Use when the user wants to remove, cancel for good, or clean up file requests they no longer need.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `file_requests.write`. Calls `POST /2/file_requests/delete`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `ids` | array of string | **yes** | File request ids to delete, from list_file_requests. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `file_requests` | array of object |  |
| `file_requests[].id` | string |  |
| `file_requests[].title` | string |  |

Also retrieved by: "get rid of that collection page for good", "cancel the thing I set up to gather uploads", "remove that request permanently".

## Triggers

Triggers are app-initiated. They are not retrievable as tools and cannot be called; subscribe with `TriggersService.CreateSubscription` and events arrive as signed deliveries.

### `file_changed`

Fires when something changes in a Dropbox account this project is subscribed to: a file added, edited, moved, or deleted anywhere in it. Carries only the affected account ids; call list_folder or get_metadata afterward to see what actually changed.

Payload fields (anything the schema does not declare never reaches a subscriber):

| Field | Type | Notes |
| --- | --- | --- |
| `list_folder` | object |  |
| `list_folder.accounts` | array of string |  |

## Inbound webhooks

Providers post to `/webhooks/dropbox`. Posts that fail verification are rejected before anything is stored, and the ingest path refuses every post while the secret variable is unset.

| Property | Value |
| --- | --- |
| Verification scheme | `hmac_sha256` |
| Shared secret | `AUTOMATON_DROPBOX_WEBHOOK_SECRET` (deployment environment) |
| Signature header | `X-Dropbox-Signature` |
| Signature format | `{sig}` |

Mappings are tried in order and the first match wins.

| Trigger | Matches when | Entity resolved from |
| --- | --- | --- |
| `file_changed` | every remaining post |  |