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

# Box

Cloud files. List, search, upload, and organize files and folders, share links, manage collaborators, and read or set metadata.

| Property | Value |
| --- | --- |
| Slug | `box` |
| Definition version | `0.1.0` |
| Base URL | `https://api.box.com/2.0` |
| Auth schemes | `oauth2` |
| Action tools | 36 |
| By class | 11 read, 17 write, 8 destructive |
| Triggers | 2 |
| Provider rate limit | 1000 requests per 1m, per account |

## Measured routing accuracy

54 golden cases replayed through the router over the whole index: measured over corpus `ea4f12ad2948` (65 toolkits, 2283 tools indexed and 13 declared uncallable), 34 cases written by hand and 20 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 | 31/54 | 57.4% |
| top-8 | 52/54 | 96.3% |

2 of the 36 action tools listed above are declared uncallable, so they are indexed nowhere and answer none of these cases. The counts here are scored over the other 34.

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://account.box.com/api/oauth2/authorize` |
| Token URL | `https://api.box.com/oauth2/token` |
| Default scopes | `root_readonly`, `root_readwrite` |
| Refresh tokens | yes, the refresh daemon renews ahead of expiry |

## Tools

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

### `box.get_file`

Get one Box file's own details by id: name, size, and when it last changed. Use when the user names a specific file. For its actual content, use download_file. For a file's structured fields instead of these basics, use get_metadata.

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /files/{{params.file_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box file id, e.g. "12345678901". |

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

| Field | Type | Notes |
| --- | --- | --- |
| `created_at` | string (date-time) |  |
| `id` | string |  |
| `modified_at` | string (date-time) |  |
| `name` | string |  |
| `parent` | object |  |
| `parent.id` | string |  |
| `parent.name` | string |  |
| `size` | integer |  |

Also retrieved by: "how big is this", "when was this last touched", "check the details on this item", "what are the basics on this document".

### `box.download_file`

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

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /files/{{params.file_id}}/content`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id 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".

### `box.get_thumbnail`

Get a small preview image for a Box file, when one can be rendered (photos, images, and many document types). Use when the user wants to see what a file looks like without downloading or opening it.

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /files/{{params.file_id}}/thumbnail.{{params.format}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the file to preview. |
| `format` | string, one of png, jpg | **yes** | Thumbnail image format. |

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 without opening it".

### `box.upload_file`

Create a new file in Box with the given content, inside a folder. Use when the user wants to add, save, or upload a document or note to Box. Content is base64-encoded. Fails if a file with that name already exists there; to add a version on top of one, use upload_new_version.

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

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `content` | string | **yes** | File content, base64-encoded. |
| `name` | string | **yes** | File name to create, e.g. "meeting-notes.txt". |
| `parent_folder_id` | string | **yes** | Box id of the destination folder. Use "0" for the root. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `entries` | array of object |  |
| `entries[].id` | string |  |
| `entries[].name` | string |  |
| `entries[].size` | integer |  |

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

### `box.upload_new_version`

Upload new content for a file that already exists in Box, keeping its name and location and adding a new version. Use when the user wants to overwrite, update, or replace what's inside an existing Box file. Content is base64-encoded. Recover an older version with restore_file_version.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `POST /files/{{params.file_id}}/content`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `content` | string | **yes** | New file content, base64-encoded. |
| `file_id` | string | **yes** | Box id of the existing file to add a version to. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `entries` | array of object |  |
| `entries[].id` | string |  |
| `entries[].modified_at` | string (date-time) |  |
| `entries[].name` | string |  |
| `entries[].size` | integer |  |

Also retrieved by: "overwrite what's inside this", "replace the content in that document", "swap out what's currently there with a fresh copy", "add a new version on top of what's there".

### `box.rename_file`

Rename a Box file, keeping its content and location. Use when the user wants to retitle or relabel a file already in Box. For putting it in a different folder instead, use move_file.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `PUT /files/{{params.file_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the file to rename. |
| `name` | string | **yes** | New file name, e.g. "Final Budget 2026.xlsx". |

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

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

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

### `box.move_file`

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

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `PUT /files/{{params.file_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `destination_folder_id` | string | **yes** | Box id of the folder to move it into. |
| `file_id` | string | **yes** | Box id of the file to move. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `parent` | object |  |
| `parent.id` | string |  |
| `parent.name` | string |  |

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

### `box.copy_file`

Duplicate a Box file into a folder, leaving the original in place. Use when the user wants their own copy or a template to build from. Optionally give the copy a new name.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `POST /files/{{params.file_id}}/copy`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `destination_folder_id` | string | **yes** | Box id of the folder the copy lands in. |
| `file_id` | string | **yes** | Box id of the file to copy. |
| `new_name` | string | no | Optional new name for the copy. Defaults to the original's name. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `parent` | object |  |
| `parent.id` | string |  |
| `parent.name` | string |  |

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

### `box.delete_file`

Move a Box file to the trash. Use when the user wants to remove or get rid of a file in Box. It stays recoverable there until someone empties it; bring it back with restore_trashed_file, or use permanently_delete_file to skip the trash for good.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `root_readwrite`. Calls `DELETE /files/{{params.file_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the file to trash. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `deleted` | boolean |  |

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

### `box.list_file_versions`

List a Box file's past versions: each version id, size, and when it was saved. Use when the user asks about earlier versions or wants to recover something they changed. Bring one back with restore_file_version.

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /files/{{params.file_id}}/versions`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the file to list versions for. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `entries` | array of object |  |
| `entries[].created_at` | string (date-time) |  |
| `entries[].id` | string |  |
| `entries[].modified_at` | string (date-time) |  |
| `entries[].size` | integer |  |

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

### `box.restore_file_version`

Make an older version of a Box file the current one. Use when the user wants to undo a change or bring back a version they lost. Requires the version id from list_file_versions.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `POST /files/{{params.file_id}}/versions/current`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the file whose version is being restored. |
| `version_id` | string | **yes** | Version id to promote, from list_file_versions. |

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

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

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

### `box.restore_trashed_file`

Bring a trashed Box file back to where it was. Use when the user wants to undelete or recover a file they, or someone else, moved to the trash. Optionally give it a new name or folder if the original spot is taken.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `POST /files/{{params.file_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `destination_folder_id` | string | no | Optional folder id to restore into, if the original folder is gone. |
| `file_id` | string | **yes** | Box id of the trashed file to restore. |
| `new_name` | string | no | Optional new name, needed if the original name is now in use. |

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

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

Also retrieved by: "undelete this, I made a mistake", "bring this back from the trash", "I need that thing I just removed", "recover the item I trashed earlier".

### `box.permanently_delete_file`

Erase a file from the Box trash for good, skipping the recovery window. Use when the user wants to permanently delete, purge, or empty out a file that is already in the trash. Cannot be undone.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `root_readwrite`. Calls `DELETE /files/{{params.file_id}}/trash`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the already-trashed file to erase. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `deleted` | boolean |  |

Also retrieved by: "wipe this out for real, don't just trash it", "empty this out of the recycle bin", "purge this item completely", "I want this gone, no recovering it".

### `box.list_folder_items`

List the files and folders directly inside a Box folder. Use for what's in this folder or browsing a known location. For finding something by name or keyword anywhere in the account, use search.

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /folders/{{params.folder_id}}/items`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | **yes** | Box folder id, or "0" for the account's root. |
| `limit` | integer | no | Items to return, max 1000. Defaults to 100. |
| `offset` | integer | no | Items to skip, for paging past the first page. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `entries` | array of object |  |
| `entries[].id` | string |  |
| `entries[].modified_at` | string (date-time) |  |
| `entries[].name` | string |  |
| `entries[].size` | integer |  |
| `entries[].type` | string |  |
| `total_count` | integer |  |

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

### `box.get_folder`

Get one Box folder's own details by id: name, size, when it last changed, and how many items it holds. Use when the user names a specific folder. For what's inside it, use list_folder_items.

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /folders/{{params.folder_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | **yes** | Box folder id, or "0" for the account's root. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `created_at` | string (date-time) |  |
| `id` | string |  |
| `item_collection` | object |  |
| `item_collection.total_count` | integer |  |
| `modified_at` | string (date-time) |  |
| `name` | string |  |
| `parent` | object |  |
| `parent.id` | string |  |
| `parent.name` | string |  |
| `size` | integer |  |

Also retrieved by: "how many things are in this folder", "check the details on this directory", "when did this folder last change".

### `box.create_folder`

Create a new folder in Box inside a parent folder. Use when the user wants to organize files into a new folder or directory in Box.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `POST /folders`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | **yes** | New folder name, e.g. "Q3 Reports". |
| `parent_folder_id` | string | **yes** | Box id of the parent folder, or "0" for the account's root. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `parent` | object |  |
| `parent.id` | string |  |
| `parent.name` | 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".

### `box.rename_folder`

Rename a Box folder, keeping its contents and location. Use when the user wants to retitle or relabel a folder already in Box. For putting it inside a different folder instead, use move_folder.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `PUT /folders/{{params.folder_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | **yes** | Box id of the folder to rename. |
| `name` | string | **yes** | New folder name. |

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

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

Also retrieved by: "retitle this directory", "give this folder a better name", "relabel this collection".

### `box.move_folder`

Move a Box folder into a different parent folder, keeping its name and contents. Use when the user wants to relocate or reorganize a folder already in Box. For giving it a new name in place, use rename_folder.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `PUT /folders/{{params.folder_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `destination_folder_id` | string | **yes** | Box id of the new parent folder to move it into. |
| `folder_id` | string | **yes** | Box id of the folder to move. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `parent` | object |  |
| `parent.id` | string |  |
| `parent.name` | string |  |

Also retrieved by: "relocate this whole directory", "put this folder somewhere else", "reorganize where this lives".

### `box.copy_folder`

Duplicate a Box folder and everything in it into another folder, leaving the original in place. Use when the user wants their own copy of a whole folder structure to build from.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `POST /folders/{{params.folder_id}}/copy`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `destination_folder_id` | string | **yes** | Box id of the folder the copy lands in. |
| `folder_id` | string | **yes** | Box id of the folder to copy. |
| `new_name` | string | no | Optional new name for the copy. Defaults to the original's name. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `parent` | object |  |
| `parent.id` | string |  |
| `parent.name` | string |  |

Also retrieved by: "I want my own version of this whole directory", "duplicate this folder structure", "clone everything in this collection".

### `box.delete_folder`

Move a Box folder to the trash, along with everything in it. Use when the user wants to remove or get rid of a folder in Box. It stays recoverable there until someone empties it; erase it for good with permanently_delete_folder.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `root_readwrite`. Calls `DELETE /folders/{{params.folder_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | **yes** | Box id of the folder to trash. |
| `recursive` | boolean | no | Required true to trash a folder that still has items in it. Defaults to false, which only succeeds on an empty folder. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `deleted` | boolean |  |

Also retrieved by: "get rid of this whole directory", "remove this folder and everything in it", "trash this collection".

### `box.permanently_delete_folder`

Erase a folder from the Box trash for good, skipping the recovery window. Use when the user wants to permanently delete, purge, or empty out a folder that is already in the trash. Cannot be undone.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `root_readwrite`. Calls `DELETE /folders/{{params.folder_id}}/trash`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | **yes** | Box id of the already-trashed folder to erase. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `deleted` | boolean |  |

Also retrieved by: "wipe this directory out for real", "empty this folder out of the recycle bin", "purge this collection completely".

### `box.search`

Search the whole Box account by keyword, across files and folders. Use when the user wants to find or locate something by name or content rather than browse a folder they already know. Optionally scope the search to one folder or one item type.

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /search`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | no | Restrict the search to this folder and its contents. Omit to search everywhere. |
| `query` | string | **yes** | Search text, e.g. "budget proposal" or "quarterly report". |
| `type` | string, one of file, folder | no | Restrict results to files or folders. Omit to search both. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `entries` | array of object |  |
| `entries[].id` | string |  |
| `entries[].modified_at` | string (date-time) |  |
| `entries[].name` | string |  |
| `entries[].size` | integer |  |
| `entries[].type` | string |  |
| `total_count` | integer |  |

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

### `box.create_shared_link_file`

Create a link to a Box file that people outside Box, or without access, can open. Use when the user wants to share, send, or get a link for a file. Optionally protect it with a password or an expiry date. For a folder instead, use create_shared_link_folder.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `PUT /files/{{params.file_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `access` | string, one of open, company, collaborators | no | Who can use the link. Defaults to company. |
| `expires_at` | string (date-time) | no | Optional time after which the link stops working. |
| `file_id` | string | **yes** | Box id of the file to link to. |
| `password` | string | no | Optional password required to open the link. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `shared_link` | object |  |
| `shared_link.access` | string |  |
| `shared_link.download_url` | string |  |
| `shared_link.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 document".

### `box.create_shared_link_folder`

Create a link to a Box folder that people outside Box, or without access, can open. Use when the user wants to share, send, or get a link for a whole folder. Optionally protect it with a password or an expiry date. For a single file instead, use create_shared_link_file.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `PUT /folders/{{params.folder_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `access` | string, one of open, company, collaborators | no | Who can use the link. Defaults to company. |
| `expires_at` | string (date-time) | no | Optional time after which the link stops working. |
| `folder_id` | string | **yes** | Box id of the folder to link to. |
| `password` | string | no | Optional password required to open the link. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `shared_link` | object |  |
| `shared_link.access` | string |  |
| `shared_link.url` | string |  |

Also retrieved by: "give me a link to this whole directory", "I want a URL for this folder I can send someone", "generate a public link to this collection".

### `box.get_shared_item`

Open a Box shared link to see the file or folder it points to, without needing to already have access. Use when the user has a Box link someone sent them and wants to know what it is before opening it in Box.

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /shared_items`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `shared_link_url` | string | **yes** | The full Box shared link URL, e.g. "https://app.box.com/s/abc123". |

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

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `size` | integer |  |
| `type` | string |  |

Also retrieved by: "what is this link someone sent me", "check what's behind this URL before I open it", "see what this shared link points to".

### `box.remove_shared_link_file`

Disable the shared link on a Box file so it stops working. Use when the user wants to unshare, revoke, or kill a file's link, without touching the file itself. For a folder's link instead, use remove_shared_link_folder.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `root_readwrite`. Calls `PUT /files/{{params.file_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the file whose shared link should be removed. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `removed` | boolean |  |

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

### `box.remove_shared_link_folder`

Disable the shared link on a Box folder so it stops working. Use when the user wants to unshare, revoke, or kill a folder's link, without touching the folder itself. For a file's link instead, use remove_shared_link_file.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `root_readwrite`. Calls `PUT /folders/{{params.folder_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | **yes** | Box id of the folder whose shared link should be removed. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `removed` | boolean |  |

Also retrieved by: "kill that link I sent for this folder", "shut off access through that directory's URL", "stop that folder's link from working".

### `box.add_collaboration`

Invite a person by email to a Box file or folder, as a viewer, editor, or another Box role. Use when the user wants to add, invite, or give someone access to something in Box.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `POST /collaborations`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `email` | string | **yes** | Email address of the person to invite. |
| `item_id` | string | **yes** | Box id of the file or folder to add the collaborator to. |
| `item_type` | string, one of file, folder | **yes** | Whether the item being shared is a file or a folder. |
| `role` | string, one of editor, viewer, previewer, uploader, co-owner | **yes** | Box collaboration role to grant. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `accessible_by` | object |  |
| `accessible_by.login` | string |  |
| `accessible_by.name` | string |  |
| `id` | string |  |
| `role` | string |  |
| `status` | string |  |

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

### `box.list_folder_collaborations`

List who has access to a Box 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 `root_readonly`. Calls `GET /folders/{{params.folder_id}}/collaborations`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `folder_id` | string | **yes** | Box id of the folder to check collaborators on. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `entries` | array of object |  |
| `entries[].accessible_by` | object |  |
| `entries[].accessible_by.login` | string |  |
| `entries[].accessible_by.name` | string |  |
| `entries[].id` | string |  |
| `entries[].role` | string |  |
| `entries[].status` | string |  |

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

### `box.update_collaboration_role`

Change the role an existing Box collaborator has on a file or folder, e.g. from viewer to editor. Use when the user wants to promote, demote, or change someone's permission level. Requires the collaboration id from list_folder_collaborations.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `PUT /collaborations/{{params.collaboration_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `collaboration_id` | string | **yes** | Collaboration id, from list_folder_collaborations. |
| `role` | string, one of editor, viewer, previewer, uploader, co-owner | **yes** | New Box collaboration role to set. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `role` | string |  |
| `status` | string |  |

Also retrieved by: "bump this person up to editor", "change what this collaborator is allowed to do", "downgrade their permission level".

### `box.remove_collaboration`

Revoke a person's collaboration on a Box file or folder. Use when the user wants to remove, kick out, or stop someone from accessing something they were added to. Requires the collaboration id from list_folder_collaborations.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `root_readwrite`. Calls `DELETE /collaborations/{{params.collaboration_id}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `collaboration_id` | string | **yes** | Collaboration id to remove, from list_folder_collaborations. |

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

| Field | Type | Notes |
| --- | --- | --- |
| `removed` | boolean |  |

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

### `box.get_metadata`

Read the structured metadata fields set on a Box file under one metadata template, e.g. status, priority, or category values a workflow tracks. Use when the user asks about a file's tags, custom fields, or classification rather than its name or size.

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /files/{{params.file_id}}/metadata/{{params.scope}}/{{params.template_key}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the file to read metadata from. |
| `scope` | string, one of global, enterprise | **yes** | Which metadata scope the template lives in. "global" for Box's built-in templates, "enterprise" for ones the account defined. |
| `template_key` | string | **yes** | The metadata template's key, e.g. "documentFlow" or "properties". |

Also retrieved by: "what tags does this have", "check the custom fields on this document", "what status or category is set on this".

### `box.set_metadata`

Attach structured metadata to a Box file for the first time under one template, e.g. tagging it with a status or category. Use when the user wants to classify, tag, or set custom fields on a file that doesn't have that template's metadata yet. To change values it already has, use update_metadata instead.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `POST /files/{{params.file_id}}/metadata/{{params.scope}}/{{params.template_key}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `fields` | object | **yes** | Field values to set, keyed by the metadata template's own field names, e.g. {"status": "Reviewed", "priority": 2}. |
| `file_id` | string | **yes** | Box id of the file to attach metadata to. |
| `scope` | string, one of global, enterprise | **yes** | Which metadata scope the template lives in. |
| `template_key` | string | **yes** | The metadata template's key, e.g. "documentFlow" or "properties". |

Also retrieved by: "tag this with a status", "classify this document", "add custom fields to this for the first time".

### `box.update_metadata`

Change specific field values in a Box file's existing metadata under one template. Use when the user wants to update, correct, or change a tag or custom field a file already carries. To attach that template's metadata for the first time, use set_metadata instead.

Class `write` (writes, no confirmation needed). Scopes `root_readwrite`. Calls `PUT /files/{{params.file_id}}/metadata/{{params.scope}}/{{params.template_key}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the file whose metadata is being changed. |
| `operations` | array of object | **yes** | JSON Patch operations against the existing fields, e.g. [{"op": "replace", "path": "/status", "value": "Approved"}]. |
| `scope` | string, one of global, enterprise | **yes** | Which metadata scope the template lives in. |
| `template_key` | string | **yes** | The metadata template's key, e.g. "documentFlow" or "properties". |

Also retrieved by: "change the status tag on this", "correct one of the custom fields on this", "update what this document is tagged with".

### `box.delete_metadata`

Remove a whole metadata template's fields from a Box file. Use when the user wants to clear, strip, or remove the tags or custom fields a template added, not just change one value.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `root_readwrite`. Calls `DELETE /files/{{params.file_id}}/metadata/{{params.scope}}/{{params.template_key}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `file_id` | string | **yes** | Box id of the file to remove metadata from. |
| `scope` | string, one of global, enterprise | **yes** | Which metadata scope the template lives in. |
| `template_key` | string | **yes** | The metadata template's key, e.g. "documentFlow" or "properties". |

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

| Field | Type | Notes |
| --- | --- | --- |
| `removed` | boolean |  |

Also retrieved by: "strip the tags off this document", "clear the custom fields on this", "remove that classification entirely".

### `box.get_current_user`

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

Class `read` (reads only). Scopes `root_readonly`. Calls `GET /users/me`.

Takes no arguments.

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

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `login` | string |  |
| `name` | string |  |
| `space_amount` | integer |  |
| `space_used` | integer |  |

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

## 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_uploaded`

Fires when a new file is uploaded into a Box folder this project is subscribed to. Carries the uploaded file's id and name; call get_file or download_file afterward for its full details or content.

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

| Field | Type | Notes |
| --- | --- | --- |
| `created_at` | string (date-time) |  |
| `source` | object |  |
| `source.id` | string |  |
| `source.name` | string |  |
| `source.type` | string |  |
| `trigger` | string |  |

### `collaboration_created`

Fires when someone is added as a collaborator on a Box file or folder this project is subscribed to. Carries the new collaboration's id and role; call list_folder_collaborations afterward to see the full membership.

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

| Field | Type | Notes |
| --- | --- | --- |
| `created_at` | string (date-time) |  |
| `source` | object |  |
| `source.id` | string |  |
| `source.role` | string |  |
| `source.status` | string |  |
| `trigger` | string |  |

## Inbound webhooks

Providers post to `/webhooks/box`. 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_BOX_WEBHOOK_SECRET` (deployment environment) |
| Signature header | `BOX-SIGNATURE-PRIMARY` |
| Signature format | `{sig}` |

Mappings are tried in order and the first match wins.

| Trigger | Matches when | Entity resolved from |
| --- | --- | --- |
| `file_uploaded` | payload `trigger` = `FILE.UPLOADED` |  |
| `collaboration_created` | payload `trigger` = `COLLABORATION.CREATED` |  |