> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/box.md).

# Box

Box cloud content management and file storage integration

* Knowledge base source

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication              |
| --------- | --------------------------- |
| Box       | OAuth sign-in               |
| Box (JWT) | JWT with an RSA private key |

#### Box

Connect to Box to access and manage your files and folders. Supports file operations, sharing, and content access.

**Set up in Box**

1. Review and grant the requested access to your files and folders.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Box**.
2. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

StackAI obtains the OAuth credentials during sign-in. You do not need to paste an access token or refresh token.

**Provider documentation:** [Setup reference](https://developer.box.com/guides/authentication/oauth2/).

#### Box (JWT)

Connect to Box using JWT (JSON Web Token) authentication for server-side applications. This method uses RSA private keys and is ideal for enterprise integrations that don't require user interaction.

**Set up in Box**

1. In the Box Developer Console, create or select an application with server authentication using JWT. Configure the application access and scopes it needs.
2. Under the application’s public-key settings, generate or upload the key pair. Record the public key ID, client ID, client secret, and enterprise ID. Keep the matching private key and its passphrase.
3. Have a Box administrator authorize the application for the enterprise. Give its service account access to the required content.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Box (JWT)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field              | Required                 | What to enter                                                                                                                                                  |
| -------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client ID                  | Yes                      | Your Box application Client ID from the Box Developer Console.                                                                                                 |
| Client Secret              | Yes                      | Your Box application Client Secret from the Box Developer Console.                                                                                             |
| Enterprise ID              | Yes                      | Your Box Enterprise ID (found in Enterprise Settings).                                                                                                         |
| JWT Key ID                 | Yes                      | The Public Key ID from your Box app configuration (Add and Manage Public Keys section).                                                                        |
| RSA Private Key            | Yes                      | RSA private key content in PEM format. Paste the contents of your .pem file from Box Developer Console. The key content will be stored securely.               |
| RSA Private Key Passphrase | Optional / as applicable | Passphrase for the encrypted private key file.                                                                                                                 |
| As User ID (Optional)      | Optional / as applicable | Optional Box user ID to impersonate when making API calls. Required when accessing user files with JWT authentication. Leave empty to use the service account. |

**Connection notes**

* The public key belongs in Box; the corresponding RSA private key belongs in StackAI. Use the passphrase for that private key when it is encrypted.
* As User ID changes the user whose files are accessed. The application must be permitted to act as that user.

**Provider documentation:** [Setup reference 1](https://developer.box.com/guides/authentication/jwt/jwt-setup/), [Setup reference 2](https://developer.box.com/guides/authentication/jwt/).

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

#### Detailed setup guides

* [Connect Box](https://docs.stackai.com/integrations/catalog/box/connect-box.md)

## Use an action

1. Add the required **Box** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Upload File

Upload a file to Box

**Inputs**

| Field                    | Type   | Required | Description                                                                                                                               |
| ------------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| File Name                | string | Yes      | The name of the file to upload.                                                                                                           |
| File Content of File URL | string | Yes      | The content of the file to upload. Can be: 1) Base64 encoded string, 2) Raw string content, or 3) A signed URL to download the file from. |
| Parent Folder ID         | string | Yes      | The ID of the parent folder to upload the file to. Use '0' for the user's root folder. Default: 0.                                        |

**Outputs**

| Field             | Type   | Description                                 |
| ----------------- | ------ | ------------------------------------------- |
| File ID           | string | The unique identifier of the uploaded file. |
| File Name         | string | The name of the uploaded file.              |
| File Size (bytes) | number | Size of the uploaded file in bytes.         |

#### Upload File Version

Upload a new version of an existing file to Box

**Inputs**

| Field                    | Type   | Required | Description                                                                                                                                                                                                 |
| ------------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| File ID                  | string | Yes      | The unique identifier that represents the file to update. The ID can be determined by visiting a file in the web application and copying the ID from the URL.                                               |
| File Content or File URL | string | Yes      | The content of the file to upload. Can be: 1) Raw string content (will be converted based on file extension), or 2) A signed URL to download the file from.                                                 |
| New File Name (Optional) | string | No       | Optional new name for the file. If specified, the file will be renamed when the new version is uploaded. If not specified, the original file name is kept.                                                  |
| If-Match (Optional)      | string | No       | Optional header to ensure the file hasn't changed since you last accessed it. Pass in the file's last observed ETag value. The upload will fail with 412 Precondition Failed if the file has changed since. |

**Outputs**

| Field             | Type   | Description                                      |
| ----------------- | ------ | ------------------------------------------------ |
| File ID           | string | The unique identifier of the file.               |
| File Name         | string | The name of the file after the version upload.   |
| File Size (bytes) | number | Size of the uploaded file version in bytes.      |
| Version Number    | number | The version number of the uploaded file version. |

#### Download File

Download a file from Box and get a signed URL

**Inputs**

| Field   | Type   | Required | Description                                                                                                                                                                                                                                                      |
| ------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| File ID | string | Yes      | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL <https://app.box.com/files/2100250645883> the file\_id is 2100250645883. |

**Outputs**

| Field             | Type   | Description                               |
| ----------------- | ------ | ----------------------------------------- |
| Uploaded File URL | string | The signed URL to download the file from. |
| File Name         | string | The name of the downloaded file.          |
| File Size (bytes) | number | Size of the downloaded file in bytes.     |

#### Get File Information

Retrieves details about a file.

**Inputs**

| Field         | Type          | Required | Description                                                   |
| ------------- | ------------- | -------- | ------------------------------------------------------------- |
| File ID       | string        | Yes      | The unique identifier of the file.                            |
| Fields        | string\_array | No       | Optional extra attributes to return.                          |
| If-None-Match | string        | No       | Optional ETag to return 304 when the file is unchanged.       |
| Box API       | string        | No       | Shared link header for accessing non-explicitly-shared items. |
| X-Rep-Hints   | string        | No       | Optional representation hints for the file.                   |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Update File

Rename, move, or update the description of a file.

**Inputs**

| Field             | Type     | Required | Description                                                                                          |
| ----------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- |
| File ID           | string   | Yes      | The ID of the file to update. Find it in the Box URL (e.g. <https://app.box.com/files/123> → `123`). |
| New File Name     | string   | No       | Rename the file. Leave blank to keep the current name.                                               |
| Move To Folder ID | string   | No       | Move the file to a different folder. Leave blank to keep its current location.                       |
| Description       | textarea | No       | Update the file's description. Leave blank to keep the current description.                          |

**Outputs**

| Field            | Type   | Description                            |
| ---------------- | ------ | -------------------------------------- |
| File ID          | string | The ID of the updated file.            |
| File Name        | string | The current name of the file.          |
| Parent Folder ID | string | The current parent folder of the file. |

#### Delete File

Deletes a file, either permanently or by moving it to the trash depending on enterprise settings.

**Inputs**

| Field    | Type   | Required | Description                                               |
| -------- | ------ | -------- | --------------------------------------------------------- |
| File ID  | string | Yes      | The unique identifier of the file (found in the Box URL). |
| If-Match | string | No       | Optional ETag to prevent deleting a changed file.         |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Copy File

Creates a copy of a file in the specified destination folder.

**Inputs**

| Field                        | Type   | Required | Description                                                                                       |
| ---------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| File ID                      | string | Yes      | The ID of the source file. Find it in the Box URL (e.g. <https://app.box.com/files/123> → `123`). |
| Destination Parent Folder ID | string | No       | The ID of the folder to copy the file into. Use `0` for the root folder. Default: 0.              |
| New File Name                | string | No       | Optional new name for the copied file. Leave blank to keep the original name.                     |

**Outputs**

| Field            | Type   | Description                          |
| ---------------- | ------ | ------------------------------------ |
| File ID          | string | The ID of the copied file.           |
| File Name        | string | The name of the copied file.         |
| Parent Folder ID | string | The folder the copy was placed into. |

#### Get Folder Information

Retrieves details for a folder, including the first 100 entries. Use List Folder Items to paginate through all contents.

**Inputs**

| Field         | Type          | Required | Description                                                   |
| ------------- | ------------- | -------- | ------------------------------------------------------------- |
| Folder ID     | string        | Yes      | The unique identifier of the folder. Root folder is 0.        |
| Fields        | string\_array | No       | Optional extra attributes to return.                          |
| If-None-Match | string        | No       | Optional ETag to short-circuit if the folder is unchanged.    |
| Box API       | string        | No       | Shared link header for accessing non-explicitly-shared items. |
| Sort          | string        | No       | Sort field for items inside the folder.                       |
| Direction     | string        | No       | Sort direction: ASC or DESC.                                  |
| Offset        | integer       | No       | Pagination offset. Default: 0.                                |
| Limit         | integer       | No       | Max items per page. Maximum: 1000.0.                          |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### List Items In Folder

Retrieves a page of items in a folder, including files, subfolders, and web links.

**Inputs**

| Field      | Type          | Required | Description                                            |
| ---------- | ------------- | -------- | ------------------------------------------------------ |
| Folder ID  | string        | Yes      | The unique identifier of the folder. Root folder is 0. |
| Fields     | string\_array | No       | Optional extra attributes to return.                   |
| Use Marker | boolean       | No       | Use marker-based pagination.                           |
| Marker     | string        | No       | Marker for marker-based pagination.                    |
| Offset     | integer       | No       | Pagination offset.                                     |
| Limit      | integer       | No       | Max items per page. Maximum: 1000.0.                   |
| Box API    | string        | No       | Shared link header.                                    |
| Sort       | string        | No       | Sort field.                                            |
| Direction  | string        | No       | Sort direction.                                        |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Create Folder

Creates a new empty folder within the specified parent folder.

**Inputs**

| Field            | Type   | Required | Description                                                                                                                                              |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Folder Name      | string | Yes      | The name for the new folder.                                                                                                                             |
| Parent Folder ID | string | No       | The ID of the parent folder. Use `0` for the root folder. Find a folder's ID in the Box URL — e.g. <https://app.box.com/folder/123> → `123`. Default: 0. |

**Outputs**

| Field            | Type   | Description                                      |
| ---------------- | ------ | ------------------------------------------------ |
| Folder ID        | string | The ID of the created folder.                    |
| Folder Name      | string | The name of the created folder.                  |
| Parent Folder ID | string | The parent folder the new folder was created in. |

#### Update Folder

Rename, move, or update the description of a folder.

**Inputs**

| Field             | Type     | Required | Description                                                                                                                                                |
| ----------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Folder ID         | string   | Yes      | The ID of the folder to update. Find it in the Box URL (e.g. <https://app.box.com/folder/123> → `123`). The root folder (ID 0) cannot be renamed or moved. |
| New Folder Name   | string   | No       | Rename the folder. Leave blank to keep the current name.                                                                                                   |
| Move To Folder ID | string   | No       | Move the folder under a different parent. Leave blank to keep its current location.                                                                        |
| Description       | textarea | No       | Update the folder's description. Leave blank to keep the current description.                                                                              |

**Outputs**

| Field            | Type   | Description                     |
| ---------------- | ------ | ------------------------------- |
| Folder ID        | string | The ID of the updated folder.   |
| Folder Name      | string | The current name of the folder. |
| Parent Folder ID | string | The current parent folder.      |

#### Delete Folder

Deletes a folder, either permanently or by moving it to the trash.

**Inputs**

| Field     | Type    | Required | Description                                            |
| --------- | ------- | -------- | ------------------------------------------------------ |
| Folder ID | string  | Yes      | The unique identifier of the folder. Root folder is 0. |
| If-Match  | string  | No       | Optional ETag to prevent deleting a changed folder.    |
| Recursive | boolean | No       | Delete a non-empty folder and all of its contents.     |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Copy Folder

Creates a copy of a folder in a destination folder. The original folder is not changed.

**Inputs**

| Field                        | Type   | Required | Description                                                                                                                                   |
| ---------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Folder ID                    | string | Yes      | The ID of the source folder. Find it in the Box URL (e.g. <https://app.box.com/folder/123> → `123`). The root folder (ID 0) cannot be copied. |
| Destination Parent Folder ID | string | No       | The ID of the folder to copy the folder into. Use `0` for the root folder. Default: 0.                                                        |
| New Folder Name              | string | No       | Optional new name for the copied folder. Leave blank to keep the original name.                                                               |

**Outputs**

| Field            | Type   | Description                                 |
| ---------------- | ------ | ------------------------------------------- |
| Folder ID        | string | The ID of the copied folder.                |
| Folder Name      | string | The name of the copied folder.              |
| Parent Folder ID | string | The parent folder the copy was placed into. |

#### Search For Content

Searches files, folders, and web links across the Box content the connection has access to. Provide a `query` or `mdfilters`.

**Inputs**

| Field            | Type     | Required | Description                                                                                                                   |
| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Query            | string   | No       | Search string. Wrap in `"..."` for an exact phrase, use `AND`/`OR` to combine terms. Required unless `mdfilters` is provided. |
| Item Type        | string   | No       | Limit to a single type: `file`, `folder`, or `web_link`.                                                                      |
| File Extensions  | array    | No       | Limit to files with the given extensions (no dots).                                                                           |
| Created After    | datetime | No       | Only return items created on or after this date/time.                                                                         |
| Created Before   | datetime | No       | Only return items created on or before this date/time.                                                                        |
| Updated After    | datetime | No       | Only return items last modified on or after this date/time.                                                                   |
| Updated Before   | datetime | No       | Only return items last modified on or before this date/time.                                                                  |
| Metadata Filters | array    | No       | Box metadata filter list (exactly one template). Required unless `query` is set. Box expects a JSON-encoded array.            |
| Limit            | integer  | No       | Max results to return (1-200). Default: 30.                                                                                   |

**Outputs**

| Field       | Type          | Description                                             |
| ----------- | ------------- | ------------------------------------------------------- |
| Total Count | integer       | Total number of items matching the query.               |
| Entries     | object\_array | The search result items (files, folders, or web links). |
| Limit       | integer       | The page size used by Box for this response.            |

#### Create Collaboration

Shares a file or folder with a user or group by creating a collaboration.

**Inputs**

| Field                   | Type    | Required | Description                                                                                                                        |
| ----------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Item ID                 | string  | Yes      | The ID of the file or folder to collaborate on. The type (file vs folder) is detected automatically.                               |
| Invite by Email         | string  | No       | Invite a user by their email address. Provide this OR `user_id` OR `group_id`.                                                     |
| User ID                 | string  | No       | Invite an existing user by their Box user ID.                                                                                      |
| Group ID                | string  | No       | Invite a group by its Box group ID.                                                                                                |
| Role                    | string  | No       | Role to grant. One of: editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner, owner. Default: editor. |
| Send Notification Email | boolean | No       | Send an email notification to the invitee. Default: true.                                                                          |

**Outputs**

| Field            | Type   | Description                                        |
| ---------------- | ------ | -------------------------------------------------- |
| Collaboration ID | string | The ID of the created collaboration.               |
| Item ID          | string | The ID of the shared item.                         |
| Role             | string | The role granted.                                  |
| Status           | string | Collaboration status (e.g. `accepted`, `pending`). |

#### Get Collaboration

Retrieves a single collaboration.

**Inputs**

| Field            | Type          | Required | Description                          |
| ---------------- | ------------- | -------- | ------------------------------------ |
| Collaboration ID | string        | Yes      | The ID of the collaboration.         |
| Fields           | string\_array | No       | Optional extra attributes to return. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Update Collaboration

Updates a collaboration — change the role or accept/reject a pending invite.

**Inputs**

| Field            | Type   | Required | Description                                                                                                                                                               |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Collaboration ID | string | Yes      | The ID of the collaboration to update.                                                                                                                                    |
| New Role         | string | No       | Change the collaboration's role. One of: editor, viewer, previewer, uploader, previewer uploader, viewer uploader, co-owner, owner. Leave blank to keep the current role. |
| Status           | string | No       | Accept or reject a pending collaboration invite. Values: `accepted` or `rejected`. Leave blank to keep the current status.                                                |

**Outputs**

| Field            | Type   | Description                          |
| ---------------- | ------ | ------------------------------------ |
| Collaboration ID | string | The ID of the updated collaboration. |
| Role             | string | The current role.                    |
| Status           | string | The current status.                  |

#### Remove Collaboration

Deletes a single collaboration.

**Inputs**

| Field            | Type   | Required | Description                  |
| ---------------- | ------ | -------- | ---------------------------- |
| Collaboration ID | string | Yes      | The ID of the collaboration. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### List File Collaborations

Lists all pending and active collaborations for a file.

**Inputs**

| Field      | Type          | Required | Description                                     |
| ---------- | ------------- | -------- | ----------------------------------------------- |
| File ID    | string        | Yes      | The unique identifier of the file.              |
| Fields     | string\_array | No       | Optional extra attributes to return.            |
| Limit      | integer       | No       | Max items per page. Maximum: 1000.0.            |
| Use Marker | boolean       | No       | Enable marker-based pagination.                 |
| Marker     | string        | No       | Pagination marker (requires Use Marker = true). |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### List Folder Collaborations

Lists all pending and active collaborations for a folder.

**Inputs**

| Field      | Type          | Required | Description                                     |
| ---------- | ------------- | -------- | ----------------------------------------------- |
| Folder ID  | string        | Yes      | The unique identifier of the folder.            |
| Fields     | string\_array | No       | Optional extra attributes to return.            |
| Limit      | integer       | No       | Max items per page. Maximum: 1000.0.            |
| Use Marker | boolean       | No       | Enable marker-based pagination.                 |
| Marker     | string        | No       | Pagination marker (requires Use Marker = true). |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Get Current User

Retrieves information about the currently authenticated user.

**Inputs**

| Field  | Type          | Required | Description                               |
| ------ | ------------- | -------- | ----------------------------------------- |
| Fields | string\_array | No       | Optional extra user attributes to return. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

### Important behavior

If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions.

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/box.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
